Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

HTTP and JSON

The API relies on HTTP for transport and uses JSON for data serialization.

JSON

All API messages must comply with RFC7493: “The I-JSON Message Format”. This RFC outlines key improvements for JSON interoperability. For reliable API usage, ensure that the JSON data you send adheres to this standard.

HTTP

We recommend using HTTP/1.1 or HTTP/2 for optimal performance. To improve efficiency, we encourage clients to maintain persistent connections between requests and limit the number of simultaneous open connections.

Key considerations for interacting with the API over HTTP:

  • URL structure: Our API endpoints do not include a trailing slash (/).
  • Case-insensitive headers: HTTP header names are case-insensitive, so clients should not rely on the case of header names.
  • Standard HTTP requirements: Ensure proper encoding of query string parameters and compliance with standard HTTP protocols.
  • Filtering results: When using query parameters to filter results, the conditions are combined using a logical AND operation.

HTTP Status Codes and Error Responses

Understanding the first digit of the HTTP status code is essential. Refer to RFC9110 for more detailed information.

Here are the most common status codes returned by the API:

200 - OK                The request was successful.
400 - Bad Request       The request is invalid, typically due to missing or
                        incorrect parameters, or referencing a non-existent
                        object. The response body will provide more details.
401 - Unauthorized      No valid API key was provided.
403 - Forbidden         The API key does not have sufficient permissions to
                        complete the request.
404 - Not Found         The requested resource with that URI doesn't exist.
                        Because a non-existing URL pattern was used.
429 - Too Many Requests The client has sent too many requests in a short period.
                        We recommend implementing exponential backoff strategies.
500, 502, 503, 504      Server Errors: Something went wrong on TandemDrive's
                        side. The `503` code is returned during maintenance.
                        In all cases, the client can retry the request later.

For 4xx status codes, the API aims to return a detailed error response in JSON format. We recommend that clients use the information in the response body, rather than relying solely on the HTTP status code, to decide on the next course of action. Check for the Content-Type: application/json header to determine if a structured JSON error message is being returned.