REST Auth API: HTTP Responses
Response formats
The response formats supported by the 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/xml
Clients are strongly advised to include an explicit Accept header in all resource
requests. If the Accept header is not 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,
a response with status 406 Unacceptable will be returned.
XML
The default API response format is XML. Clients should request this format by specifying the media type application/xml in their HTTP request Accept header.
An example is given below showing the default XML representation for an Event.
GET https://api.example.org/api/2012-02-01/auth/resources/events/456/ HTTP/1.1 Host: api.example.org Accept: application/xml Accept-Encoding: gzip Authorization: Basic 0123456789abcdef
<Event> <EventID>456</EventID> <UniqueIdentifier>a34fc9dc-1fa0-9019-b39a-d0fe91119ed6</UniqueIdentifier> <Code>MGMT101-001</Code> <StartDateTime>2012-02-02T09:00:00.000+12:00</StartDateTime> <FinishDateTime>2012-02-03T17:00:00.000+12:00</FinishDateTime> <StartTimeZoneAbbr>NZDT</StartTimeZoneAbbr> <FinishTimeZoneAbbr>NZDT</FinishTimeZoneAbbr> <Description>2 days, 9:00AM - 5:00PM</Description> <LocationName>Wellington</LocationName> <Status>Completed</Status> <CreatedDateTime>2012-01-01T04:28:00.5Z</CreatedDateTime> <LastModifiedDateTime>2012-01-01T09:25:05.703Z</LastModifiedDateTime> <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/456/"/> <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/EventTemplate" type="application/xml" title="EventTemplate" href="https://demo.arlo.co/api/2012-02-01/auth/resources/eventtemplates/123/"/> <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Logistics" type="application/xml" title="Logistics" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/456/logistics/"/> <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Sessions" type="application/xml" title="Sessions" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/456/sessions/"/> <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/RegistrationSettings" type="application/xml" title="RegistrationSettings" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/456/registrationsettings/"/> <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Registrations" type="application/xml" title="Registrations" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/456/registrations/"/> <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/PublicationSettings" type="application/xml" title="PublicationSettings" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/456/publicationsettings/"/> <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/PublicationStatus" type="application/xml" title="PublicationStatus" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/456/publicationstatus/"/> <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/CommunicationSettings" type="application/xml" title="CommunicationSettings" href="https://demo.arlo.co/api/2012-02-01/auth/resources/events/456/communicationsettings/"/> <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/TimeZone" type="application/xml" title="TimeZone" href="https://demo.arlo.co/api/2012-02-01/auth/resources/timezones/1/"/> <Link rel="related" type="text/html" title="WebsiteRegister" href="http://www.example.org/register?sgid=a34fc9dc-1fa0-9019-b39a-d0fe91119ed6"/> </Event>
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.
Exceptions
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.
The REST API attempts to return exceptions in the HTTP response body when something goes wrong. In XML, these appear as an <ApiException> element in the content body. An exception has up to
two properties:
| Property | Description |
|---|---|
| Code |
Describes the type of the error. Examples are ParseException, QueryParseException, HttpException, ArgumentException.
|
| Message | A more descriptive message about the error. |
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 XML response. While the API does endeavour to return descriptive XML 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.
Examples
Example 1
A simple 404 Not Found error.
GET /api/2012-02-01/auth/resources/eventtemplates/99999/
<ApiException> <Code>NotFound</Code> <Message>Requested resource could not be found.</Message> </ApiException>
Example 2
A 400 Bad Request error due to an invalid filter query parameter.
GET /api/2012-02-01/auth/resources/eventtemplates/?filter=12345
<ApiException> <Code>QueryParseException</Code> <Message>Expression of type 'Boolean' expected (at index 0)</Message> </ApiException>
HTTP response status codes
200 OK
The request was successful and the response body contains the requested resource.
HTTP/1.1 200 OK Content-Length: 2042 Content-Type: application/xml; charset=utf-8 <?xml version="1.0" encoding="utf-8"?> <Event> <EventID>456</EventID> <UniqueIdentifier>a34fc9dc-1fa0-9019-b39a-d0fe91119ed6</UniqueIdentifier> <Code>MGMT101-001</Code> <StartDateTime>2012-02-02T09:00:00.000+12:00</StartDateTime> <FinishDateTime>2012-02-03T17:00:00.000+12:00</FinishDateTime> <StartTimeZoneAbbr>NZDT</StartTimeZoneAbbr> <FinishTimeZoneAbbr>NZDT</FinishTimeZoneAbbr> <Status>Completed</Status> <CreatedDateTime>2012-01-01T04:28:00.5Z</CreatedDateTime> <LastModifiedDateTime>2012-01-01T09:25:05.703Z</LastModifiedDateTime> ... </Event>
201 Created
The request to create the resource was successful and the response body contains the newly-created resource.
308 Permanent Redirect
The requested resource has been moved. A new GET request should be made using the URI in the Location HTTP response header.
HTTP/1.1 308 Permanent Redirect Location: https://demo.arlo.co/api/2012-02-01/events/420/
400 Bad Request
The request was not valid. For GET requests, this is usually due an invalid query parameter such as filter or orderby. For POST or PUT requests, this is usually due to invalid XML structure or element values.
HTTP/1.1 400 Bad Request Content-Type: application/xml; charset=utf-8 Content-Length: 180 <?xml version="1.0" encoding="utf-8"?> <ApiException> <Code>ParseException</Code> <Message>Queries using field 'Description' are not supported (at index 0)</Message> </ApiException>
401 Unauthorized
The supplied credentials, if any, are not sufficient to access the resource. Ensure your username and password are correct and that the user has been added to the API User group.
HTTP/1.1 401 Unauthorized Content-Length: 0 WWW-Authenticate: Basic
403 Forbidden
The requesting user has been denied access to the resource due to lack of permissions.
HTTP/1.1 403 Forbidden Content-Type: application/xml; charset=utf-8 Content-Length: 183 <?xml version="1.0" encoding="utf-8"?> <ApiException> <Code>SecurityException</Code> <Message>User does not have the required privileges to access this resource.</Message> </ApiException>
404 Not Found
The requested resource could not be found.
HTTP/1.1 404 Not Found Content-Type: application/xml; charset=utf-8 Content-Length: 145 <?xml version="1.0" encoding="utf-8"?> <ApiException> <Code>NotFound</Code> <Message>Requested resource could not be found.</Message> </ApiException>
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/xml 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-Type: application/xml; charset=utf-8 Content-Length: 168 <?xml version="1.0" encoding="utf-8"?> <ApiException> <Code>HttpException</Code> <Message>No acceptable content types were supplied in the request.</Message> </ApiException>
409 Conflict
The resource could not be updated because it contains values that conflict with those on the server. For POST and PUT requests, this means
that the submitted resource has values such as CreatedDateTime or LastModifiedDateTime which are not consistent with the current values because the resource
has changed since it was last retrieved.
HTTP/1.1 409 Conflict Content-Type: application/xml; charset=utf-8 Content-Length: 183 <?xml version="1.0" encoding="utf-8"?> <ApiException> <Code>Conflict</Code> <Message>LastModifiedDateTime conflicts with current value "2014-02-10T21:44:46.210Z"</Message> </ApiException>
415 Unsupported Media Type
The request could not be processed because the it did not contain a recognised Content-Type header indicating the media type of the submitted HTTP body content. This header should contain a media type value such as application/xml.
HTTP/1.1 415 Unsupported Media Type 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, an XML content body 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/xml; charset=utf-8 Content-Length: 145 <?xml version="1.0" encoding="utf-8"?> <ApiException> <Code>InternalServerError</Code> <Message>General internal error.</Message> </ApiException>
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
Unknown and missing elements
Missing elements
The REST API avoids outputting empty or null properties in generating representations. For example, if a Contact resource has no value for the CodeSecondary property, this element is omitted from the 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.
Unknown elements
As the REST API evolves over time, it is important clients using it make allowances for the presence of new or unknown elements.
Whereever possible, REST API clients should avoid rigid or strict parsing of representations against a fixed set of elements. Specifically:
- Parsing of XML representation elements should be order and index agnostic.
- Parsing of XML representations should silently ignore unknown elements.
Major breaking changes to the API which include significant changes to the semantic meaning or format of existing elements will be handled with a new major API version release with a new, independent set of endpoints. Minor (non-breaking) changes to the API will be released against existing endpoints with new elements and/or links being introduced to existing resources as required.