API Response Structures

POS Hub API responses are designed to be consistent and predictable, making it easier for developers to integrate with the platform. This guide outlines the structure of API responses, including object and list responses, error handling, and best practices.

Overview

There are 3 primary response types in the POS Hub API:

1. Object Responses: These responses return a single object representing a resource, such as a location, product, or order.
2. List Responses: These responses return an array of objects, typically used for endpoints that retrieve multiple resources, such as a list of locations or products.
3. Error Responses: These responses indicate an error occurred during the request, providing details about the error.

Object Responses

Object responses are used when a request successfully retrieves a single resource. The response will always include a 200 OK status code and a JSON object representing the resource.

Every object response will have at least a single property called data, which contains the resource data. The structure of the object will vary depending on the resource type.

Example Object Response

{
  "data": {
    "id": "location_123",
    "name": "Main Street Store",
    "address": "123 Main St, Anytown, USA",
    "createdAt": "2023-10-01T12:00:00Z",
    "placedAt": "2023-10-01T12:00:00Z"
  }
}

List Responses

List responses are used when a request retrieves multiple resources. The response will include a 200 OK status code and a JSON object containing an array of resources.

Every list response will have at least a single property called data, which contains the array of resource data. The structure of the array will vary depending on the resource type.

Example List Response

{
  "data": [
    {
      "id": "location_123",
      "name": "Main Street Store",
      "address": "123 Main St, Anytown, USA",
      "createdAt": "2023-10-01T12:00:00Z",
      "placedAt": "2023-10-01T12:00:00Z"
    },
    {
      "id": "location_456",
      "name": "Second Street Store",
      "address": "456 Second St, Anytown, USA",
      "createdAt": "2023-10-01T12:00:00Z",
      "placedAt": "2023-10-01T12:00:00Z"
    }
  ]
}

The List Response map also include information about pagination, specifically the hasNextPage and nextPageKey properties, which indicate whether there are more pages of results and the key to retrieve the next page, respectively.

Example Paginated Response:

{
  "data": [
    {
      "id": "location_123",
      "name": "Main Street Store",
      "address": "123 Main St, Anytown, USA",
      "createdAt": "2023-10-01T12:00:00Z",
      "placedAt": "2023-10-01T12:00:00Z"
    }
  ],
  "hasNextPage": true,
  "nextPageKey": "<token>"
}

Error Responses

Error responses are returned when a request fails due to an error, such as invalid input, unauthorized access, or server errors. The response will include an appropriate HTTP status code (e.g., 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error) and a JSON object containing error details.

Every error response should at least have a error property, which contains a string that describes the error. Optionally.

Example Error Response

{
  "error": "Invalid request parameters"
}

See the Error Handling Guide for more details on how to handle errors in your application.

Our Guarantee

We strive to ensure that every single API response from the POS Hub API will conform to the structure outlined in this guide. This consistency allows developers to build robust applications that can handle responses predictably.