People API Documentation - Version 1

Resources - Person (People)

A person represents an individual associated with BAS, either by virtue of active or past employment or through collaboration.

This data is sourced from the BAS People Database and filtered to include people who are: active Employees OR Collaborators (including Students).

Resource model

Name Property Name Data Type Optional Description
ID id String No Unique identifier
Encoded ID encoded_id String No A non-predictable version of the person’s ID, this is safe to use within public URLS
Shortref ID shortref_id String Yes An optional vanity override of the person’s Encoded ID
Phone phone String Yes A person’s phone extension
Show phone show_phone String Yes Binary: ‘1’/’0’ meaning True/False
Email ID email_id String No The person’s NERC username referred to in this resource as a person’s alias
E-mail Address email_address String Yes This MAY or MAY NOT be an @bas.ac.uk address
Name - title name_title String Yes This will be returned in the correct case without a trailing full stop
Name - first name_first String Yes This will be returned in the correct case
Name - middle name_middle String Yes This will be returned in the correct case
Name - last name_last String Yes This will be returned in the correct case
Preferred name - title pref_name_title String Yes This will be returned in the correct case without a trailing full stop
Preferred name - first pref_name_first String Yes This will be returned in the correct case
Preferred name - last pref_name_last String Yes This will be returned in the correct case
Job title job_title String Yes This will be returned in the correct case
Show job title show_job_title String Yes Binary: ‘1’/’0’ meaning True/False
Biography biography String Yes Self authored description of a person,returned as JSON escaped HTML. Deprecated! [1]
Research interests research_interests String Yes Self authored description of a non-controlled research interests,returned as JSON escaped HTML. Deprecated! [1]
Collaborations collaborations String Yes Self authored description of a person’s partnerships and collaborations ,returned as JSON escaped HTML. Deprecated! [1]
Publications publications String Yes Self authored description of a person’s papers [2],returned as JSON escaped HTML. Deprecated! [1]
Avatars avatars Avatar Yes A person may have a number of avatars (images) to visually represent the person in different contexts Deprecated! [1]
updated_on updated_on DateTime No This field can be used as a true measure of when this resource was last changed

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

[1] This information is provided on a limited, temporary basis for the sole purpose of populating the new BAS public website with existing rich person information.

[2] This description MAY or MAY NOT include a person’s NORA papers in addition to non-NORA papers and may be
formatted in a range of syntax styles. Multiple syntax styles may be used in the same description.

Formatting a person’s name for display

A person’s name should be displayed in the form: “pref_name_title. pref_name_first pref_name_last”.

Example (JSON)

{
    "id": "123",
    "encoded_id": "7811b11947b1395efb7ebd6e3d7cd5d6",
    "shortref_id": "DavidVaughan",
    "phone": null,
    "show_phone": "1",
    "email_id": "dgv",
    "name_title": "Prof",
    "name_first": "David",
    "name_middle": "Glyn",
    "name_last": "Vaughan",
    "pref_name_title": null,
    "pref_name_first": "David",
    "pref_name_last": null,
    "job_title": "Director of Science",
    "show_job_title": "1",
    "updated_on": "2015-02-20 08:00:14",
    "email_address": "dgv@bas.ac.uk",
    "avatars": [
        {
            "context": "external",
            "display_sizes": [
                {
                    "name": "full",
                    "mime-type": "image/jpeg",
                    "href": "http://www.antarctica.ac.uk/about_bas/contact/staff/image.php?id=7811b11947b1395efb7ebd6e3d7cd5d6&size=full"
                }
            ]
        }
    ],
    "biography": "<p>Free form HTML Content - Omitted for readability</p>",
    "research_interests": "<p>Free form HTML Content - Omitted for readability</p>",
    "collaborations": null,
    "publications": "<p>Free form HTML Content - Omitted for readability</p>"
}

Resource methods

[GET]/people

Returns a listing of all people, ordered by their last then first name in ascending order.

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/people/v1/people

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": [
        {
            "id": "175",
            "encoded_id": "ee5291096640b1f3721d1d262c9d4f52",
            "shortref_id": "povl",
            "phone": "1401",
            "show_phone": "1",
            "email_id": "epab",
            "name_title": "Dr",
            "name_first": "Einar",
            "name_middle": "Povl",
            "name_last": "Abrahamsen",
            "pref_name_title": null,
            "pref_name_first": "Povl",
            "pref_name_last": null,
            "job_title": "Observational Oceanographer",
            "show_job_title": "1",
            "updated_on": "2015-02-20 08:00:06",
            "email_address": "epab@bas.ac.uk",
            "avatars": [
                {
                    "context": "external",
                    "display_sizes": [
                        {
                            "name": "full",
                            "mime-type": "image\/jpeg",
                            "href": "http:\/\/www.antarctica.ac.uk\/about_bas\/contact\/staff\/image.php?id=ee5291096640b1f3721d1d262c9d4f52&size=full"
                        }
                    ]
                }
            ],
            "biography": null,
            "research_interests": null,
            "collaborations": null,
            "publications": "<p>Free form HTML Content - Omitted for readability</p>"
        },
        {
            "id": "296",
            "encoded_id": "2d3c7f73e9df9cf8efb673728f4a72de",
            "shortref_id": "eyoung",
            "phone": "1307",
            "show_phone": "1",
            "email_id": "eyoung",
            "name_title": "Dr",
            "name_first": "Emma",
            "name_middle": "Frances",
            "name_last": "Young",
            "pref_name_title": null,
            "pref_name_first": "Emma",
            "pref_name_last": null,
            "job_title": "Physical Biological Modeller",
            "show_job_title": "1",
            "updated_on": "2015-02-20 08:00:11",
            "email_address": "eyoung@bas.ac.uk",
            "avatars": [ ],
            "biography": "<p>Free form HTML Content - Omitted for readability</p>",
            "research_interests": "<p>Free form HTML Content - Omitted for readability</p>",
            "collaborations": "<p>Free form HTML Content - Omitted for readability</p>",
            "publications": "<p>Free form HTML Content - Omitted for readability</p>"
        }
    ],
    "meta": {
        "count": 605
    }
}

[GET]/people/{id|alias}

Returns a specified person, either by their ID or their alias.

Traits
Trait Enabled
Authenticated Yes
Parameters
Name Field Name Data Type Required Valid Value(s) Description
Reference {id:alias} Integer : String Yes A person->id : A person-alias Used to specify which person to return

If the Reference parameter is numeric the API will try to find a person by ID, otherwise the API will try to find a person by alias. It is not to possible to try both properties, nor is it possible to override which property is used.

Note: For formatting reasons parameter field names substitute the | character with : and otherwise have exactly the same meaning.

Options

None.

Example request

URL: https://api.bas.ac.uk/people/v1/people/1946 OR
URL: https://api.bas.ac.uk/people/v1/people/felnne

The first URL uses a Person ID, the second a Person alias.

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 Success)
Headers (Redundant headers removed)
Key Value
Content-Type application/json
Body (JSON)
{
    "data": {
        "id": "1946",
        "encoded_id": "d85d6ac062cd72cd545035afeea243de",
        "shortref_id": "felix",
        "phone": null,
        "show_phone": "0",
        "email_id": "felnne",
        "name_title": "Mr",
        "name_first": "Felix",
        "name_middle": "Wolfe",
        "name_last": "Fennell",
        "pref_name_title": null,
        "pref_name_first": "Felix",
        "pref_name_last": null,
        "job_title": "Web Systems Developer",
        "show_job_title": "1",
        "updated_on": "2015-02-20 08:00:14",
        "email_address": "felnne@bas.ac.uk",
        "avatars": [],
        "biography": "<p>Free form HTML Content - Omitted for readability</p>",
        "research_interests": null,
        "collaborations": null,
        "publications": null
    }
}
Example response (404 Not Found)

Using URL: https://api.bas.ac.uk/people/v1/people/does-not-exist.

Headers (Redundant headers removed)
Key Value
Content-Type application/json
Body
{
    "errors": [
        {
            "details": {
                "model_reference_error": {
                    "person": [
                        "No person could be found by either id or alias using a reference of: [does-not-exist]."
                    ]
                }
            },
            "resolution": "Ensure you are providing a valid person id or alias.",
            "type": "model_not_found"
        }
    ]
}

Note: The format of this error will change in future API versions (to standardise against the json:api spec.

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.