API Documentation

# API Responses

As much as possible, we use standard responses for all API endpoints. We use HTTP status codes to convey the result of the request and standard response objects within the responses.

# HTTP Headers

Unless otherwise noted in the endpoint document, all API endpoints return the following HTTP header:

Content-Type: application/json; charset=utf-8

# Response Objects

All API endpoints will return an ApiResponse object - our standard envelope with common properties and notifications. There are variations of this object for lists of data. Notifications are a way we can pass additional information in a response. All the response objects contain an array of notifications.

Each object is detailed below. The endpoint documentation will indicate which response object is used for the specific endpoint.

# ApiResponse

The ApiResponse object is used when the endpoint returns a single object. The endpoint documentation will indicate which object is contained within the data property.

Name Required Type Description
message true string A message that may contain more information regarding the response.
notifications true ApiResponseNotification[] The list of notifications for the response. See ApiResponseNotification for more information.
data false object The resource, data or payload. This is usually an object but could be a simple type such as a string or an integer. The endpoint documentation will indicate what it is.

A JSON example of the object is below:

{
    "message": "The operation succeeded!",
    "notifications": [],
    "data": {
        // The data property will contain a single object or resource.
    }
}

There are 2 variations to this object for lists which are described below.

# ApiListResponse

The ApiListResponse object is used when the endpoint returns data in the form of lists or arrays. The endpoint documentation will indicate which object is contained within the data property.

Name Required Type Description
message true string A message that may contain more information regarding the response.
notifications true ApiResponseNotification[] The list of notifications for the response. See ApiResponseNotification for more information.
numberOfRecords true int The number of records returned in the response.
data false object[] The resources, data or payload. This is usually an array of objects. The endpoint documentation will indicate what it is.

A JSON example of the object is below:

{
    "message": "The operation succeeded!",
    "notifications": [],
    "numberOfRecords": 5,
    "data": [
        {
            // The data property will contain an array of objects or resources.
        }
    ]
}

# ApiPagedListResponse

The ApiPagedListResponse object is used when the endpoint returns data in the form of lists or arrays and supports paging of that data. The endpoint documentation will indicate which object is contained within the data property.

Name Required Type Description
message true string A message that may contain more information regarding the response.
notifications true ApiResponseNotification[] The list of notifications for the response. See ApiResponseNotification for more information.
numberOfRecords true int The number of records returned in the response. May not match the totalRecords property value if paging is enabled and the current page is the last page.
totalRecords true int The total number of records in the database after any filtering has been applied.
pageSize true int The number of records requested on the page, if paging was requested.
pageNumber true int The current page number, if paging was requested.
pageCount true int The number of pages available considering the values of the pageSize and totalRecords properties.
hasPreviousPage true boolean An ISO 8601 formatted date string specifying the date and time when the the original image was uploaded.
hasNextPage true boolean An ISO 8601 formatted date string specifying the date and time when the the original image was last modified.
data true object[] The resources, data or payload. This is usually an array of objects. The endpoint documentation will indicate what it is.

A JSON example of the object is below:

{
    "message": "The operation succeeded!",
    "notifications": [],
    "numberOfRecords": 50,
    "totalRecords": 34001,
    "pageSize": 50,
    "pageNumber": 1,
    "pageCount": 7,
    "hasPreviousPage": false,
    "hasNextPage": true,
    "data": [
        {
            // The data property will contain an array of objects or resources.
        }
    ]
}

# ApiErrorResponse

The ApiErrorResponse object is used when the endpoint returns an error. The ApiResponseNotification array will usually contain details regarding the error or errors.

Name Required Type Description
message true string A message that may contain more information regarding the response.
traceIdentifier false string A unique identifier for the request.
instance false string An identifier for the instance. Typically contains the request URL.
notifications true ApiResponseNotification[] The list of notifications for the response. See ApiResponseNotification for more information.

A JSON example of the object is below:

{
    "message": "The operation failed!",
    "traceIdentifier": "80001078-0001-ed00-b63f-84710c7967bb",
    "instance": "/v1.0/images/274577DE-5AD1-4552-B493-3F2F49E3D2C4",
    "notifications": [
        {
            "severity": "Error",
            "text": "The image requested is not an image or is an image with an unknown format.",
            "code": null,
            "additionalData": null
        }
    ]
}

# ApiResponseNotification

The ApiResponseNotification object is used in the other API response objects listed above to convey additional information. The notifications are not only used in error responses and can be sent in the success response to a request.

Name Required Type Description
severity true string The notification severity. Values will be one of: Success or Error or Warning or Information
text true string Provides the notification detail.
code false string A code for the specific notification, where applicable.
additionalData false object This object may contain additional data pertinent to the error. Not widely used. Would be described in the endpoint documentation.

A JSON example of the object used as part of a successful Get Menu request is below:

{
    "message": "The operation succeeded!",
    "notifications": [
        {
            "severity": "Warning",
            "text": "The requested version '202005' has been replaced with version '202012'. Please use the new version.",
            "code": "",
            "additionalData": null
        }
    ],
    "data": {
        "key": "SPUR-ZA-19",
        "version": 202005,
        "revision": "4413566902",
        "name": "Spur - Standard - Take-away - 1st Party",
        "displayName": "Take-Away",
        "description": "Standard Menu available for the brand app",
        // Other properties omitted for brevity.
    }
}

# HTTP Status Codes

All API endpoints will respond with standard HTTP status codes. The endpoint documentation will indicate which status code is used for successful requests.

# Success

Success responses use the ApiResponse or ApiListResponse or ApiPagedListResponse objects described above.

200
OK
Our standard success response.
201
Created
For requests that create resources.
202
Accepted
Used for running long running processes to indicate that the request has been accepted.

# Errors

Error responses use the ApiErrorResponse object described above wherever possible.

400
Bad Request
Returned for validation errors, poorly constructed requests or pretty much anything else not listed below.
401
Unauthorized
Returned to indicate that the client lacks valid authentication credentials for the requested resource.
403
Forbidden
Returned to indicate that the client is not permitted to access the requested resource.
404
Not Found
Returned when the resource that was requested could not be found.
500
Server Error
Returned when an unexpected error occurred on the server.

Note that depending on where the request was rejected, the response may not contain our standard error response object - for example, if the request is rejected on our API gateway the response is served before it arrived on our servers.

←