.. _response-object:

The Response Object
===================

This section covers how responses from the API are formatted, and what to expect when handling data.

Basic Format
------------

Every reponse will be returned with the following format:

.. code-block:: JSON

	{
	  "id": 0,
	  "apiVersion": "0.0.0",
	  "meta": {
	    "authors": [
	      "National Oceanography Centre"
	    ],
	    "copyright": "Copyright 2020 National Oceanography Centre",
	    "email": "products@noc-innovations.co.uk"
	  },
	  "links": {
	    "info": {
	      "href": "https://appstst.noc-innovations.co.uk/software"
	    },
	    "disclaimer": {
	      "href": "https://appstst.noc-innovations.co.uk/api/polpred-api/disclaimer"
	    }
	  },
	  "params": { },
	  "data/error": { }
	}

Parameters
''''''''''

Every API will return the parameters that given to the call. The exception to this is the ``key`` parameter, which will be hashed out:

.. code-block:: JSON

	{
	  "params": {
	    "key": "################",
	  }
	}

Data/Error Objects
''''''''''''''''''

All responses will contain one of two objects (but **never** both):

* ``data`` - Call was made successfully and data has been returned.
* ``error`` - Call was made but there has been an error in retrieving information.

.. note:: The ``error`` object will only reference API errors and will not catch server wide errors such as 404.

Data Object
-----------

The data object returned in a successful call to the API will contain all of the information regarding the requested data, including additional meta information. The main data will always be contained within an ``items`` array, accompanied by a ``totalItems`` key/value pair, indicating how many items have been returned. Additional meta information may include how data was computed, and data units or headers.

Example Data Object
'''''''''''''''''''

Below is an example response from a Compute Time Series computation (See :ref:`available-functions`):

.. code-block:: JSON
	:emphasize-lines: 19, 20

	{
	  "data": {
	    "model": {
	      "name": "NW Europe CS3X Model (Depth averaged 10HC)",
	      "code": "CS3X_10HC"
	    },
	    "datum": {
	      "name": "Mean Sea Level",
	      "code": "msl"
	    },
	    "headers": {
	      "dt": "Date/Time",
	      "etc..."
	    },
	    "units": {
	      "dt": "utc",
	      "etc..."
	    },
	    "totalItems": 96,
	    "items": [
	      {
	        "dt": "2019-10-01T00:00:00Z",
	        "etc..."
	      },
	    ]
	  }
	}

Error Responses
---------------

Error responses can occur for different reasons, such as invalid parameters given to a call, or trying to make a call that the user does not have access to. All error responses will be given a HTTP ``400 Bad Request`` response status code, which makes a convenient way to check for errors which integrating into software.

Example Error Object
''''''''''''''''''''

There are two main error response types:

* | **Code/Message**:
  | Used for the majority of error responses, used to give a basic indication of what error has occured.

  .. code-block:: JSON

  	{
	  "error": {
	    "code": 400,
	    "message": "There is an error with parameter 'dt_start' or it has not been declared."
	  }
	}

* | **Errors Array**:
  | ``errors`` is used when multiple parameters have been given. For example, if multiple ``licence_ids`` have been declared and none are successful, an array is returned giving the error for each one.

  .. code-block:: JSON

	{
	  "error": {
	    "errors": [
	      {
	        "code": 400,
	        "modelCode": "CS3X_10HC",
	        "message": "Date and time specified outside of licence period."
	      }
	    ]
	  }
	}