HTTP Requests and Responses

All requests should expect to receive JSON ( Content-Type: application/json ) and to be encoded as UTF-8.

All requests will be sent over HTTPS.

The API service is located at https://www.osti.gov/award-doi-service/api/v1

Get Existing Award Information

GET /api/v1/<osti_id>

All GET requests will be used to retrieve a JSON representation of a single award record using the OSTI ID number that was given on creation of the record.

GET /api/v1/?site_award_id=<site_award_id>

An alternative is to use your site’s award number to retrieve the record, if it exists. Otherwise identical to the previous call.

Submit New Award

POST /api/v1

New awards are submitted by sending the JSON submission object via a POST request with the data as the body, encoded as JSON and send with Content-Type: application/json

Award data will be validated, and any errors will be returned to the caller. Please see Anatomy of a Submission

Update Award Data

PUT /api/v1/<osti_id>

Note

REST normally suggests PATCH as the correct verb here, but that is not a part of the HTTP/1.1 standard and so is not currently supported. We are instead overloading the PUT verb to handle these requests.

Awards that have already been submitted can have metadata updated. Each update is a separate operation and should be sent as an array. Operations that are invalid or that have invalid data will be ignored and will not return an error. Items that are otherwise correct but contain processing errors will be skipped and errors will be returned for those items. The possible operations are listed below.

{"op": "add", "<field name>": "<field value>"}

The add operation can be used to add one or more investigators or related identifiers. These will be appended to the end of the existing entries for this record. For example:

[
    {
        "op": "add",
        "related_idents": [
            {
                "relation": "isReferencedBy",
                "identifier": "http://example.com/url",
                "type": "uri"
            }
        ]
    }
]
                                                

{"op": "update", "<field name>": "<field value>"}

The update operation can be used to replace the value of one of the metadata fields. Only certain fields can be replaced: award_title, award_description, award_funding_type, award_urls, award_date_range_start, award_date_range_end, related_idents, investigator, and ident_nums. This will overwrite the existing value in the field indicated. For example:

[
    {
        "op": "update",
        "award_title": "This is the new title"
    }
]