Response

Envelope

Every response is contained by an envelope. Each response has a predictable set of keys with which you can expect to interact with. The route definitions indicate what the 'data' field will contain. They do not indicate what the meta fields will be populated with. Each key uses the underscore naming convention.

{
  "success": true,
  "code": 602,
  "message": Request OK,
  "status_code": 200,
  "status_message": "OK",
  "detailed": [  
     {
         "field": "field_name",
         "message": "Human readable message"
     },
  ]

  "data" : [
    ...

  ],

  "count": integer, 
  "pagination": {
    "next": "url_to_next",
    "prev": "url_to_prev"
  }
}

Meta Fields

The success field returns whether the operation was successful or not. The code field is the API code returned by the call. (These live on doc.staging right now) The message field is the string representation of the API code. The status_code represents the HTTP status_code from the operation This is present in case the user is accessing the API not using HTTP. The status_message is the name of the status_code. On a 400 error, the detailed field contains an array of objects containing the field names that did not validate along with a message for what that field did not validate. On other errors it will be simply an array of human readable messages for what went wrong. This will always be null on success.

Pagination

The count field contains the total amount of records in existence for the route. The pagination object contains convenient links to get the next and prev data if a call to a GET request exceeds the limit in the query parameter. For example if the call is limited to 300 results in the data objects. But there are 500 total results. The first call would return the first 300 and a link to get the next 200.

Caveat
If the result set is say 20 results with an offset of 5, the previous link will contain information to get the first 5 results even if the count is specified at 20. This prevents overlapping when cursoring through the data.

Status Codes

The possible status codes are the following:
200 OK - Successful operation. Is returned with a message body.
201 Created - Successful creation of an object.
401 Unauthorized - User does not have access to the API
403 Forbidden - User does not have the required permission to view specific data.
400 Bad Request - Client error in request sent to the server.
404 Not Found - Request/Resource not found.
409 Conflict -- Returned when trying to add something that already exists.
429 Conflict -- Returned when the rate limit is exceeded.
500 Internal Server Error - Issue detected on the server.

POST & PATCH

POST & PATCH requests will set the location header of the value that was modified or added. A POST request (in the case of creating a new resource) will return the id of the resource created in the data body. PATCH will not contain data in the response.