All response bodies are JSON or JSON API encoded.
JSON:
A single resource is represented as a JSON object:
{
"field1": "value",
"field2": true,
"field3": []
}
Below is a specific example of a single resource presented as a JSON object:
{
"code": "CUST",
"description": "Customer Transfers",
"comments": []
}
A collection of resources is represented as a JSON array of objects:
[
{
"field1": "value",
"field2": true,
"field3": []
},
{
"field1": "another value",
"field2": false,
"field3": []
}
]
Below a specific example of a collection of resources represented as a JSON array of objects:
[
{
"code": "CUST01",
"description": "Customer Transfers",
"comments": []
},
{
"code": "CONTACT",
"description": "Contact Transfers",
"comments":
["created_at": 2017-08-27T16:14:57Z",
"created_by": "xxname",
"comment": "updated transfer" },
"created_at": 2017-08-28T15:19:34Z",
"created_by": "xxname",
"comment": "<p>adjusted</p> - ready to run"}
]
},
"code": "Invoice" ,
"description": "Invoice Transfers",
"comments":[]
},
...
]
JSON API:
A single resource is represented as a JSON API object:
{
"data":{
"id": "1",
type": "groups",
"attributes":
{ "code": "codename",
"description": "description of group"
},
relationships":{
"comments": {}
}
}
}
}
Below a specific example of a single resource JSON API object:
{
"data":
[{
"id": "8",
"type": "groups",
"attributes": {
"code": "CUST01",
"description": "Customer Transfers"
},
"relationships": {
"comments": {
"data": []
}
}
}]
}
}
A collection of resources is represented as a JSON API array of objects:
{
"data":
[
{
"id":"1",
"type":"groups",
"attributes":{ //...this groups'attributes
"code": "codename",
"description": "description of group"
},
"relationships":
{ //...this groups'relationships
"comments": {
"data": [
{
"id":"5",
"type":"comments"
},
{
"id":"6",
"type":"comments"
}
]
}
}
}
],
"included":
[
{
"type": "comments",
"id": "5",
"attributes": {
"created_at": "yyyy-mm-ddThh:mm:ssZ",
"created_by": "author-name",
"comment": "text for the comment"}
},
{
"type": "comments",
"id": "5",
"attributes": {
"created_at": "yyyy-mm-ddThh:mm:ssZ",
"created_by": "author-name",
"comment": "text for the comment"
}
}
]
}
Below a specific example of a collection of resources represented as a JSON API array of objects:
{
"data": [
{
"id": "8",
"type": "groups",
"attributes": {
"code": "CUST01",
"description": "Customer Transfers"
},
"relationships": {
"comments": {
"data": [
]
}
}
},
{
"id": "2",
"type": "groups",
"attributes": {
"code": "CONTACT",
"description": "Contact Transfers"
},
"relationships": {
"comments": {
"data": [
{
"id": "10",
"type": "comments"
},
{
"id": "12",
"type": "comments"
}
]
}
}
},
{
"id": "5",
"type": "groups",
"attributes": {
"code": "INVOICE",
"description": "Invoice Transfers"
},
"relationships": {
"comments": {
"data": [
]
}
}
},
...
],
"included": [
{
"id": "10",
"type": "comments",
"attributes": {
"created-at": "2017-08-27T16:14:57Z",
"created-by": "xxname",
"comment-text": "updated transfer"
}
},
{
"id": "12",
"type": "comments",
"attributes": {
"created-at": "2017-08-28 15:19:34Z",
"created-by": "xxname",
"comment-text": "adjusted
- ready to run"
}
}
]
Timestamps are in UTC and formatted as ISO8601.
Unset fields will be represented as a null instead of not being present. If the field is an array, it will be represented as an empty array - ie [].
We use HTTP status codes to indicate the success or failure of a request.
Success codes:
200 OK - Request succeeded. Response included201 Created - Resource created.204 No Content - Request succeeded, but no response body.Error codes:
400 Bad Request - Could not parse the request401 Unauthorized - No authentication credentials (token) provided or authentication failed403 Forbidden - The Authenticated API user does not have access404 Not Found - Resource not found415 Unsupported Media Type - POST/PUT/PATCH request occurred without a application/json content-type422 Unprocessable Entry - A request to modify or create a resource failed due to a validation error429 Too Many Requests - Request rejected due to rate limiting 500, 501, 502, 503, etc - An internal server error occurredAll 400 series errors (400, 401, 403, etc) will be returned with a JSON or JSON API object in the body and a application/json or application/vnd.api+json content-type respectively.
{ "message": "Not Found" }500 series error codes (500, 501, 502, etc) do not return JSON or JSON API bodies.
In case of validation errors on a POST/PUT/PATCH request, a 422 Unprocessable Entry status code will be returned. The JSON response body will include an array of error messages.
{
"message": "Validation Failed",
"errors": [
{
"message": "Field is not valid"
},
{
"message": "OtherField is already used"
}
]
}