Arlo

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.