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

JSON

{
  "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

JSON

{
  "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

JSON

{
  "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

JSON

{
  "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.