API Responses

Response Document Structure

The returned media type MUST conform to the value provided in the API request Accept header, or the 1st supported media type if multiple values are specified. The default content type is JSON (application/json).

If the requested media type(s) are unsupported, the server MUST return an HTTP response status 415 Unsupported Media Type.

Operations on a Resource Collection

A GET performed on a resource collection (without specifying a resource Id) will return potentially multiple resource instances, and MUST return the collection in a “data” array, which provides a predictable document path to resource data. The data array must be returned even when the response is a collection of one.

e.g. GET /v1/persons

Response

// 200 OK
Content-Type: application/json; charset=utf-8

{
   "data": [
       {
           "applicationId": "65648987234",
           "familyName": "SMITH",
           "givenName": "John",
           "birthDate": "1990-01-01"
       },
       {
           "applicationId": "878795465",
           "familyName": "DOE",
           "givenName": "Jane",
           "birthDate": "1986-03-01"
       }
   ]
}

NOTE: Arrays containing very large datasets or large binary objects, such as documents or images, MUST be controlled by pagination. Total payload size MUST NOT exceed 10 Mb. It is suggested that payload size SHOULD NOT exceed 2 Mb, an historical default payload maximum for a number of platforms.

A POST may also be performed on a resource collection to create a new instance of the resource. A unique and immutable resource identifier MUST be created and returned by the resource owner and SHOULD be returned as a payload field in the form of ‘{resourceName}Id’ or ‘{resourceName}_id’. Additional derived data MAY be returned as deemed appropriate. The server MUST return a ‘Location’ header containing the relative path of the newly created resource, e.g. ‘/persons/65648987235’. A links object MAY be returned if required, for instance to return a version link in cases where a versioned change history is maintained.

e.g. POST /v1/persons

Response

// 201 Created
Content-Type: application/json; charset=utf-8
Location: /persons/65648987235
{
   "data": {      
      "personId": "65648987235",
   }
}

Operations on a UI/Experience Resource Instance

A top-level member or root element is not required for a UI/experience, functional or ‘private’ API response document unless the request is unsuccessful, in which case an ‘errors‘ collection - an array of error objects - SHOULD be returned, as outlined in the Error Handling section of this standard.

Operations on a Business Information Resource Instance

A business information resource is a specific data asset acted upon and managed through a state life-cycle by a specific business process. A business information resource will have value outside of its specific sub-domain, and will belong to a System of Record (SoR), the definitive source of the data through all stages of the resource life-cycle. Resource models will typically be distilled via a process of Domain Driven Design. Examples of business information resources might include ‘accounts’ or ‘clients’.

A canonical business information resource response document SHOULD contain at least one of the following top-level members:

The members ‘data’ and ‘errors’ MUST NOT coexist in the same document.

A GET request to the parent resource SHOULD return root-level resource data only, SHOULD provide links to identify sub-resources, and MAY provide links to identify existentially related objects.

The ‘meta’ top-level element provides a mechanism for the provision of meta-data, such as copyright, timestamp, origin, ownership, and dissemination delimiter. If a ‘meta’ member is to be returned, its content MUST be defined in the API specification.

Example response document:

{
    "meta": {
        "dlm": "sensitive:personal",
        "copyright": "Copyright 2015 Example Corp.", 
        "totalPages": 13
    }
    "data": {  
        "documentId": "3456789", 
        "title": "declaration", 
        "uploaded": "2018-05-22T14:56:29.000Z", 
        "updated": "2015-05-22T14:56:28.000Z 
    }
    "links": {
        "self": "http://example.com/v1/documents/3456789"
    }
}

Response Headers

The recommended, and default content type is JSON (application/json).

The following response headers SHOULD be included in all responses:

The following response headers MAY be included in responses:

HTTP Response Codes

Not all HTTP status codes are mandatory, or will apply to every operation. The table below indicates the HTTP Response codes that SHOULD be supported at a minimum for each HTTP method.

Status Code Definitions and their correct application are defined by RFC 2616