API Responses

The following responses are sent from the ITAS API:

• 200 - OK.
• 201 - OK, New resource created.
• 400 - Bad Request - The request was invalid. The exact error should be explained in the error payload. e.g. Invalid Json, missing attributes.
• 401 - Unauthorised - The request requires authentication.
• 403 - Forbidden - The server understood the request, but is refusing it or the access is not allowed.
• 404 - Not Found - The URI data is incorrect.
• 500 - Internal Server Error - This error is not returned by the application but by the server.

The ITAS Response Envelope

All responses from ITAS API V2 endpoints are contained within a response envelope. This is a new feature of V2 and does not exist in V1. The Envelope contains four parts, each part is only sent in the response if it is populated:

• Data - used for the body data e.g. a list of entities or details of a specific entity, or the id of an entity after it has been created. This can be either an array or an object depending on the endpoint called.
• Pagination - when the response contains a list of entities, the pagination section includes meta-data associated with the list. Object.
• Response - used to denote the response type e.g. success or failure. Always a string.
• Messages - used to return error, warning and information messages. Array.

Example:

Pagination

The Pagination section of the response envelope describes the dataset returned in the Data part of the response envelope:

• Total - total number of records in the dataset.
• Top - how many records can be returned. The default is 200 and if there are more than 200 records in the available dataset only 200 will be returned by default. This can be overridden by adding a Limit value to the Odata querystring i.e. $limit=1000
• Skip - the position of the first record to be returned from the dataset. i.e. $offset=100 will return records starting at position 101.
• Returned - actual number of records returned.

The following pagination describes the records returned as: 146 records, starting at position 401, from a total or 547 records with a limit of 200. Note that the reason only 146 records are returned when 200 are requested is that the dataset finishes before the 200'th record is found.

Error Responses

Error responses are generally served as 400 Bad Request, the exact details can be found in the message payload. All responses follow the same format.

Where Messages are an array of Severity with SeverityMessageDetail and Message with ErrorMessageDetail. One of the several internal error messages is detailed below

Inner Error Message Codes

Detailed error messages are delivered as part of 400 and 404 responses and are sent in the following format

For example

Combining the Error Response and the Error Messages, the response will take the following format. Error Messages is an array which if expected will contain multiple Messages.

The table below shows a list of error messages and their codes.