Project API Documentation - Version 1

Resources - Collection (Collections)

A Collection is a grouping of projects under a logical structure. Collections are used to access related projects and they may or may not have a hierarchy within that collection.

This data is sourced from the BAS Projects Database.

Resource model

Name Property Name Data Type Optional Description
ID id Integer No Unique identifier
Valid From valid_from Date Yes Date represents the approximate date that the collection either began or is valid from.
Valid To valid_to Date Yes Date represents the approximate date that the collection either finished or is valid unto.
Name name String No Name of collection - will indicate what the general purpose of the collection is.
Description description String No Full description of collection that outlines purpose of groupings.
Project Types project_types Array of ProjectTypes Yes Lists the available Project Types that will be used in this collection. If blank no project types will be included in projects.
NERC Vocab Identifier nerc_vocab_identifier NERC Vocab Identifier No Unique identifier of collection as used in the NERC Vocabulary Server.
Root Project ID root_project_id Integer Yes If the project includes hierarchical relationships this will be the ID of the root project to start the hierarchy from.
Projects projects Array of Projects Yes List of project objects.
Inserted on insert_on DateTime No DateTime of insert of record
Updated on update_on DateTime No DateTime of update of record

Note: This model is liable to change in future API versions.

Example (JSON)

{
    "valid_from": "2015-03-01",
    "valid_to": null,
    "created_at": "2015-01-30 15:39:50",
    "updated_at": "2015-01-30 15:39:50",
    "description": "Organisational units for presenting on BAS Website redevelopment",
    "name": "BAS Teams - Web Site Demo",
    "project_types": [
        {
            "description": "BAS Public Website team - 2015-",
            "name": "Team",
            "id": "TEAM2015",
            "nerc_vocab_identifier": {
                "list": "ZZ5",
                "code": "TEAM2015"
            }
        },
        {
            "description": "BAS Public Website project - 2015-",
            "name": "Project",
            "id": "PROJ2015",
            "nerc_vocab_identifier": {
                "list": "ZZ5",
                "code": "PROJ2015"
            }
        }
    ],
    "id": 7,
    "nerc_vocab_identifier": {
        "list": "ZZ1",
        "code": "BASPSPE2"
    },
    "root_project_id": 32
    }
}

Resource methods

[GET]/collections

Returns a listing of all collections. Project objects are not included. You must request an individual Collection to obtain a list of projects belonging to that collection.

Includes a meta array containing the number of resources returned.

Traits
Trait Enabled
Authenticated Yes
Parameters

None.

Options

None.

Example request

URL: https://api.bas.ac.uk/projects/v1/collections

Note: Interactive examples for this method may be covered in the examples document.

Headers
Key Value
Content-Type application/json
Accept application/json
Body (Raw)

N/A

Example response (200 OK)
Headers
Key Value
Content-Type application/json
Body (JSON)

Note: For brevity, only the first and last records are shown.

{
    "data": [
        {
            "valid_from": "2015-03-01",
            "valid_to": null,
            "created_at": "2015-01-30 15:39:50",
            "updated_at": "2015-01-30 15:39:50",
            "description": "Organisational units for presenting on BAS Website redevelopment",
            "name": "BAS Teams - Web Site Demo",
            "project_types": [
                {
                    "description": "BAS Public Website team - 2015-",
                    "name": "Team",
                    "id": "TEAM2015",
                    "nerc_vocab_identifier": {
                        "list": "ZZ5",
                        "code": "TEAM2015"
                    }
                },
                {
                    "description": "BAS Public Website project - 2015-",
                    "name": "Project",
                    "id": "PROJ2015",
                    "nerc_vocab_identifier": {
                        "list": "ZZ5",
                        "code": "PROJ2015"
                    }
                }
            ],
            "id": 7,
            "nerc_vocab_identifier": {
                "list": "ZZ1",
                "code": "BASPSPE2"
            },
            "root_project_id": 32
        },,
    ],
    "meta": {
        "count": 411
    }
}

[GET]/collections/{id|code}

Returns a specified project by its ID or NERC Vocab Identifier Code. The NERC Vocab Identifier code is a string and can be seen when viewing a full list of collections.

Traits
Trait Enabled
Authenticated Yes
Parameters
Name Field Name Data Type Required Valid Value(s) Description
ID {id} Integer Yes A collection -> id Used to specify which collection to return
Code {code} String Yes A *project -> nerc_vocab_identifier -> code * Used to specify which collection to return but specifies a NERC Vocab Server collection code
Options

None.

Example request

URL: https://api.bas.ac.uk/projects/v1/projects/3 OR URL: https://api.bas.ac.uk/projects/v1/projects/BASPSPE OR

Note: Interactive examples of this method may be covered in the examples document.

Headers
Key Value
Content-Type application/json
Accept application/json
Body (Raw)

N/A

Example request (200 OK)
Headers (Redundant headers removed)
Key Value
Content-Type application/json
Body (JSON)
{
    "data": {
        "valid_from": "2015-03-01",
        "valid_to": null,
        "root_project_seq": 32,
        "created_at": "2015-01-30 15:39:50",
        "updated_at": "2015-01-30 15:39:50",
        "description": "Organisational units for presenting on BAS Website redevelopment",
        "name": "BAS Teams - Web Site Demo",
        "project_types": [
            {
                "description": "BAS Public Website team - 2015-",
                "name": "Team",
                "id": "TEAM2015",
                "nerc_vocab_identifier": {
                    "list": "ZZ5",
                    "code": "TEAM2015"
                }
            },
            {
                "description": "BAS Public Website project - 2015-",
                "name": "Project",
                "id": "PROJ2015",
                "nerc_vocab_identifier": {
                    "list": "ZZ5",
                    "code": "PROJ2015"
                }
            }
        ],
        "id": 7,
        "nerc_vocab_identifier": {
            "list": "ZZ1",
            "code": "BASPSPE2"
        },
        "root_project_id": 32,
        "projects": [
            {
                "name": "Air unit",
                "short_name": null,
                "insert_by": null,
                "insert_on": null,
                "update_by": null,
                "update_on": null,
                "id": 41,
                "date_start": null,
                "date_finish": null,
                "people": [
                    {
                        "id": 2118,
                        "email_address": "dea@bas.ac.uk",
                        "email_id": "dea",
                        "name_reference": "dea"
                    },
                    {
                        "id": 1818,
                        "email_address": "craoma@bas.ac.uk",
                        "email_id": "craoma",
                        "name_reference": "craoma"
                    }
                ]                
                "project_type": {
                    "description": "BAS Public Website team - 2015-",
                    "name": "Team",
                    "id": "TEAM2015",
                    "nerc_vocab_identifier": {
                        "list": "ZZ5",
                        "code": "TEAM2015"
                    }
                },
                "parent_id": 37
            },
            ...
        ]
    },
    "meta": {
        "count": 1
    }
}
Example request (404 Not Found)

Using URL: https://api.bas.ac.uk/projects/v1/projects/0.

Headers (Redundant headers removed)
Key Value
Content-Type application/json
Body (JSON)
{
    "errors": [
        {
            "details": {
                "model_reference_error": {
                    "project": [
                        "No project could be found with an id of: [0]."
                    ]
                }
            },
            "resolution": "Ensure you are providing a valid project id.",
            "type": "model_not_found"
        }
    ]
}

Note: The format of this error will change in future API versions (to standardise against the [json:api spec][http://jsonapi.org/format/#errors].

This information may be out of date whilst this website is being redeveloped. Until then, if you have any problems using an API documented here, please contact the relevant project maintainer.