Response Format

Introduction

This section covers the responses, content formats, and error codes returned by the API.

Where possible, the HTTP status code will be accurate to the response given. Currently, server-side scripts cannot alter the response status code, and will always return 200 OK or 422 Unprocessable Content.

Response Body

All schema endpoints, and document endpoints by default, will return application/json content responses. The response will always be an object, containing the timestamp property with the server's current system time.

If the request was successful, the returned value (if available) will be stored in the data property. This value can be of any type, depending on the requested endpoint or the script that was called.

If the request failed, the returned error details will be stored in the error property.

Error Responses

The error response object will follow a fixed format.

{
    "timestamp": "2024-06-31T10:59:54.327Z",
    "error": {
        "type": "/errors/http/notfound",
        "status": 404,
        "title": "Not Found",
        "instance": "/<CollectionID>/collections"
    }
}

Response object keys are defined as:

Property	Type	Description
type	String	String/URI that indicates the type of error thrown. Currently no corresponding endpoint is available to explain what they mean.
status	Integer	Matches the HTTP status code.
title	String	Short help text which describes the error, may not be populated if a generic HTTP response is given - such as 404 Not Found.
instance	String	URI of the request that lead to this error.
detail	String	Different/longer help text which should give a more comprehensive description/explanation of the error.
ex	Object	JS error thrown by the API, if available.

Accept Header

The

GET

and

SEARCH

endpoints for documents allow the client to specify the Accept header, specifying the content type of the response data. If an acceptible media type is given, the typical response structure may be ignored in order to return data correctly in the requested format.

Some media types will cause the API to return binary data instead of a plain text body.

Acceptable media types:

• application/json (default)
• application/xml
• application/vnd.openxmlformats-officedocument.spreadsheetml.sheet *
• text/csv

* returns binary data, not plain text.

Other Accept headers will return a 406 Not Acceptable response status with no body.