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:

{
  "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:

{
  "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 Available Functions):

{
  "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.

  {
    "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.

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