Standard Response

All authenticated responses follow structured json. Responses are divided into 3 types depending on their status field.

Status	Description	Required Keys	Optional Keys
`success`	When a request is deemed successful. Requested was processed as expected.	`status`, `data`	`pagination`
`failure`	When input data to api does not match server side validations or constraints	`status`, `data`	`message`, `errors`, `code`
`error`	When server could not process the input data	`status`, `errors`, `message`	`data`, `code`

Fields¶

status: This field will be present in all authenticated responses. Values are one of success, failure and error.
data: This is a polymorphic field and changes as per the api endpoint. In case of success this will be the resource of interest. In case of failure this will be a failures object.
message: A string field the details of why a failure or error has happened.
errors: An array of error objects detailing attribute level errors for input data.
code: A string field of error code. Based on the code, api client can take additional action in their workflow
pagination: This field will be available when the response has a large result set. Only a delta of the result set is made available; details total size, pages is also given using which client can make another api call to fetch next batch of the result set. See Pagination for more details.

Errors/Failures object¶

Field	Data Type	Description
`attribute_name`	string	Name of the input attribute.
`messages`	string array	Failure/Error messages associated with the `attribute_name`.

Pagination¶

pagination object is available on the response when api call has large result set.

Paginated Response Snippet

{
    "status": "success",
    "data": [ ], // some array of objects
    "pagination": {
        "total_count": 62,
        "current_page": 1,
        "total_pages": 7        
    }
}

Pagination Snippet

{
  "total_count": 62,
  "current_page": 1,
  "total_pages": 7
}

Field	Data Type	Description
`total_count`	integer	Total items in the result set.
`current_page`	integer	current page in the request set.
`total_pages`	integer	total available pages in the request set.

Result set on the api call can be controlled by query parameters page and per_page

Field	Data Type	Description
`page`	integer	page number of interest.
`per_page`	integer	number of items to be reported in the api call.

Http Status Codes¶

There is no relationship between http status code and the response object structure. See below some conventions that are used in this api

Http Code	Response Status	Description
`2xx`	`success`	For 2xx api response, it is safe to expect that response status is always `success`.
`422`	`failure`	It is safe to expect that response status is always going to be `failure`