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 :ref:`anatomy`


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"
        }
    ]