API Response Format
There are four common variations of responses that SHOULD be handled when integrating with the API. The following JSON examples does not show real responses of the API. To see a glossary of all the responses, refer to API Code Glossary or examples for each API endpoint.
Generic Responses
Generic responses are to provide information and debugging information in the case of errors or operational success. Sometimes, an operation such as clearing tracker inventory or similarly clearing repeater inventory only emphasis success which can be easily assumed by the HTTP response.
However, in cases where there are multiple operational responses and errors such as paging an order that could already be paged or does not have a tracker associated with order, the returnCode
can be used to identify those instances easily, especially since most carry common HTTP status codes such as 400 Bad Request
or 200 OK
.
Success/Warning Responses
Property | Description | Type |
---|---|---|
status | HTTP Status Code | integer |
returnCode | Return Code (>=1000) to identify positive/neutral generic responses. | integer |
message | Describes successful operation. | string |
{
"status": 200,
"returnCode": 1000000000,
"message": "There is cake."
}
For responses that only provide confirmation that an operation is successful or warning, the JSON response will include status
(integer) which mirrors the HTTP status code (Usually 200), returnCode
(integer) which will be 1000 or greater for positive/neutral responses, and message
(string) to describe the successful operation.
Integrator SHOULD identify by the returnCode
, especially if there are multiple positive/neutral responses.
Error Responses
Property | Descriptio | Type |
---|---|---|
status | HTTP Status Code | integer |
returnCode | Return Code (<0) to identify error responses | integer |
message | Describes unsuccessful operation. | string |
{
"status": 404,
"returnCode": -10000000000,
"message": "The cake is a lie."
}
Similar to the generic response, error responses have a NEGATIVE returnCode
(integer) to indicate if an error occurs.
500 Internal Error
If you receive such an error, please report the response and where it occurs as soon as possible either in the Support section or by contacting LRSUS.
Data Responses
In the case of data responses which will contain more than the result of an operation, the returnCode
will be a constant integer for each endpoint. (e.g. Retrieving all active orders and clearing all active orders are made through same endpoint, and will have a returnCode
of 2)
List Responses
Property | Description | Type |
---|---|---|
status | HTTP Status Code | integer |
warning | Warning message in case there are discrepancies. | string, optional |
returnCode | Return Code(1-999) to describe responses with data returned. | integer |
count | Number of items returned. | integer |
items | Array of objects for endpoints that return multiple data. Property of object will vary. | array |
{
"status": 200,
"warning": "Number of cakes may dwindle.",
"returnCode": 999,
"count": 2,
"items": [{"type": "chocolate", "icing": "vanilla"}, {"type": "vanilla", "icing": "vanilla"}]
}
For list responses such as retrieving /activeorders
, /orders
, or any other API endpoint that may have multiple items, responses WILL contain status
(integer), returnCode
, count
, and items
. It MAY OR MAY NOT include warning
, but SHOULD be checked for.
Individual Responses
Property | Description | Type |
---|---|---|
status | HTTP Status Code | integer |
warning | Warning message in case there are discrepancies. | string, optional |
returnCode | Return Code(1-999) to describe responses with data returned. | integer |
{
"status": 200,
"returnCode": 998,
"cakesEaten": 2,
"cakesMade": 6,
"cakesTotal": 8
}
For individual responses, the properties will vary and will have to be referred to, but every response will have at least status
, returnCode
, and an optional warning
if it exists.
Updated about 3 years ago