In this article
An HTTP Response is what you get when you make an HTTP Request.
There are two important properties of a response that you should care about:
HTTP Status Code - this tells you at a protocol level what the status of the response is
Response Payload - this is the body of the response. It is in a standard format that will give you the application level status, the results, and if applicable, any errors.
Response Formats
All responses are returned using JSON. JSON is a lightweight serialization language that is compatible with many different languages. JSON is syntactically correct JavaScript code, meaning you can use the Javascript eval() function to parse it.
Response Payload
We comply with HATEOAS, or Hypermedia As The Engine Of Application State. This means that our Rest APIs are accessible through the use of hypermedia links, and that all resources returned by our APIs contains a "links" property.
Example (Single resource payload)
{
"id": 15,
"name": "John Doe",
"links": {
"self": "/resource/15",
"sub-resource": "/resource/15/sub-resource"
}
}
Example (Resource collection payload)
{
"itemCount": 100,
"totalCount": 23533,
"items": [
{
"id": 14,
"name": "test1"},
{
"id": 16,
"name": "test2"}
],
"links": {
"item": "/resource/{id}",
"self": "/resource?pageSize=100&page=1",
"next": "/resource?pageSize=100&page=2",
}
}
Note: The item-link is used to get the link to an individual item in the collection. The {id} parameter is replaced with the "id"-property on the item itself.
HTTP Status Codes
Our REST APIs use standard HTTP status codes to indicate success or failure of API calls. Below are the most common codes our APIs support. To learn more about Status Codes, see Wikipedia.
| HTTP Status Code | Message | Description |
|---|---|---|
200 |
OK |
The request was processed and returned successfully. Nothing was changed. |
201 |
Created |
The new resource was created successfully |
400 |
Bad Request |
Problem with the request, such as a missing, invalid or type mismatched parameter |
401 |
Unauthorized |
The request did not have valid authorization credentials |
403 |
Forbidden |
Private data you are not allowed to access, or you’ve hit a rate limit. |
404 |
Not Found |
Your URL is wrong, or the requested resource doesn’t exist |
500 |
Server Error |
Internal server error. If this persists, please contact support. |
503 |
Service Unavailable |
Our API is down. Please try again later. |