REST Pub API: HTTP responses

Response formats

The response formats supported by the public REST API are documented in this section.

HTTP content negotiation is used to determine the format or representation to use via the HTTP request Accept header in client requests.

The API currently supports the following response media types:

application/json

Clients are strongly advised to include an explicit Accept header in all resource requests, or use the format query parameter to indicate the expected response content type. Further details on these is available in the articles for each particular resource.

If nether parameter is supplied in a request, the REST API will use a default response type which may change between API versions, so omitting this header is not recommended. If an Accept header is supplied but does not contain any recognised media types and no valid format query parameter is present, a response with status 406 Unacceptable will be returned.

JSON

The default API response format is JSON. Clients should request this format by specifying the media type application/json in their HTTP request Accept header, or by including the query parameter format=json.

An example is given below showing the default JSON representation for a Presenter.

GET https://api.example.org/api/2012-02-01/pub/resources/presenters/10569/?format=json
Host: api.example.org
Accept-Encoding: gzip

{
   "PresenterID":10569,
   "FullName":"Danny Foxworth",   
   "ViewUri":"http://acme.example.org/presenters/10569-danny-foxworth"
}

Compression (GZip)

For clients that support it, the REST API supports GZip compression of HTTP responses. Compression can be enabled by specifying gzip in the Accept-Encoding header of HTTP requests. Use of this option is highly recommended for performance as it decreases the time required to download a response from the service.

By default, clients calling endpoints using JavaScript in a web browser do not need to manage this as the browser will automatically add this header. Clients using server HTTP request libraries may need to manually add this or specifically enable compression for requests and responses.

Errors

The primary mechanism used to indicate success or failure with API requests is via the HTTP response status code field. For HTTP GET requests, a status code of 200 represents success. Status codes of 400-599 indicate an error response, and the client may choose to parse the response body to get further information regarding the error.

General structure

The REST API attempts to return exceptions in the HTTP response body when something goes wrong. In JSON, these appear as an error structure in the content body. An exception has up to two properties:

Property	Description
Code	Describes the type of the error. Examples are `BadRequest`, `NotFound`, `ArgumentException`.
Message	A more descriptive message about the error (if available).

When handling HTTP responses with error codes (in the 400-599 range), clients must check the HTTP response Content-Type header prior to attempting to parse any expected JSON response. While the API does endeavour to return descriptive JSON representations of errors, it is not always possible, and responses from other infrastructure such as load balancers and firewalls may return results using unexpected content types such as text/plain or text/html or may include no content body at all.

Parsing HTTP `Content-Type` response header

When determining if it is safe for your code (particularly JavaScript) to parse the body of an error response, you will need to check the response's Content-Type header to ensure it is JSON and not some other type. Failing to check this header and always attempting to parse the content body as JSON is likely to result in errors in some situations.

When checking this header, avoid direct string equality comparisons as the value may include a content encoding or charset parameter. For example, a response may declare the Content-Type as:

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

Attempting to check using the expression (contentType == "application/json") is not reliable (and will fail in this example). Our recommended solution is to use an expression like (contentType != null && contentType.indexOf("application/json") === 0) which can safely allow for additional text after application/json.

HTTP response status codes

The GET response codes in this section are applicable only for direct server requests, or requests from web browsers supporting CORS (for cross domain requests). For legacy web browsers using JSONP, see JSONP response codes.

HTTP GET response codes

200 OK

The request was successful and the response body contains the requested resource.

HTTP/1.1 200 OK 
Content-Length: 599
Content-Type: application/json; charset=utf-8  

{
   "PresenterID":10569,
   "FullName":"Danny Foxworth",   
   "ViewUri":"http://acme.example.org/presenters/10569-danny-foxworth"
}

400 Bad Request

The request was not valid. Usually due an invalid query parameter such as filter, or an invalid fields value. The response body contains an error structure.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Length: 180

{
   "Code":"BadRequest",
   "Message":"Unsupported filter 'foo'"
}

403 Forbidden

The requesting user has been denied access to the resource due to lack of permissions. The response body contains an error structure.

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: 180

{
   "Code":"SecurityException",
   "Message":"User does not have the required privileges to access this resource."
}

404 Not Found

The requested resource could not be found. The response body contains an error structure.

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
Content-Length: 180

{
   "Code":"NotFound",
   "Message":"The requested resource could not be found"
}

406 Unacceptable

The client did not specify any recognised or acceptable media types in its Accept header. Clients should include one of the supported media response types such as application/json in the HTTP Accept header. The REST API uses this header to determine the format or representation to use when generating responses. If the header is not supplied, the API will select a default response type.

HTTP/1.1 406 Unacceptable
Content-Length: 0

500 Internal Server Error

The requested resource could not be returned because of an internal error.

Depending on the nature of the internal error, a JSON error structure may be returned containing details of the exception, however this may not always be possible. Clients should check the Content-Type HTTP response header before attempting to parse the response body.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8
Content-Length: 180

{
   "Code":"InternalServerError",
   "Message":"User does not have the required privileges to access this resource."
}

503 Service Unavailable

The API is temporarily down for maintenance. Wait for a few minutes and try again.

Clients should check the Content-Type HTTP response header before attempting to parse the response body.

HTTP/1.1 503 Service Unavailable
Content-Type: text/plain
Content-Length: 0

JSONP response codes

JSONP requests almost always return a 200 OK response, including when there is an error. The callback function specified in the request is invoked with a response object which either contains a structure representing the requested resource (if successful), or a structure with error information (if failed).

Error responses are denoted by the presence of a { Success: false } value in the callback response object. This parameter is omitted for successful responses.

The response content type for JSONP requests is always application/javascript.

200 OK (JSONP success)

The request was successful and the response body contains a callback with the requested resource.

HTTP/1.1 200 OK 
Content-Length: 599
Content-Type: application/javascript; charset=utf-8  

myCallback({
   "PresenterID":10569,
   "FullName":"Danny Foxworth",   
   "ViewUri":"http://acme.example.org/presenters/10569-danny-foxworth"
});

200 OK (JSONP failure)

The request was not successful and the response body contains a callback with an error structure. The structure contains a field Success with the value false.

HTTP/1.1 200 OK 
Content-Length: 599
Content-Type: application/javascript; charset=utf-8  

myCallback({
   "Success":false,
   "Code":"DuplicateRegistration",
   "Message":"Julie Everett (julie.everett@example.org) is already registered for this event"
});

503 Service Unavailable

The API is temporarily down for maintenance. Wait for a few minutes and try again.

A response with a callback is not likely to be generated in this situation.

HTTP/1.1 503 Service Unavailable
Content-Type: text/plain
Content-Length: 0

Missing fields

The REST API avoids outputting empty or null properties in generating JSON representations. For example, if an Event resource has no value for the Code property, this element is omitted from the JSON representation. Clients should treat a missing element as the equivalent of null for that property.

Unless otherwise stated, clients should assume all elements of a resource are optional.