Content Types 

The Web API allows the client to specify the response format either using the content type in the accept header of the request or by specifying the format in the query string using the format parameter.

For example:

/names/00050fc9-8c49-4ec3-9d46-2eef4d4d70d1?format=json

The default content-type is XML.

The Content-Type that is sent with each request to the API indicates which format the response will be for GET requests and what format the API expects the request body to be in the case of PUT or POST requests.

Response Codes

Based on RESTful principles this API returns the relevant conventional HTTP Status codes depending on the outcome of processing the request message.

When an application receives a response from the API it should first check the HTTP response code before trying to decode the response body. If a request is successful you will get a status code response in the 200 range and sometimes it will be accompanied by XML or JSON in the response body. E.g. If you successfully request a name then you would get a 200 response back with the XML/JSON for that name in the body. If a request fails you will get a non 200 status code and often a description of why the request failed.

Here are some of the common responses codes.

Dates

XML

All dates and times are reported using the ISO8601 format (e.g. 2012-01-12T14:00:00Z).

JSON

The format used for dates in the JSON response is likely to change in the near future as the formatter used by the web services is going to standardise on the same as the XML i.e. ISO8601.