Using the API

Here you can find more information on how to use this API. See the additional pages for more deep dives on authentication, pagination, etc.

Requests

The API accepts HTTP requests and all endpoints follow the same format.

HTTP Method

The HTTP method describes the action you want to take on a resource. We use standard HTTP methods for all our resources, e.g., GET, POST, UPDATE, and DELETE.

The usual requirements and behavior of each HTTP method are described below. To learn more about scopes, see Using the API: Authentication.

HTTP Method	Required Scope	Description
`GET`	`*.read`	Fetch a specific resource or collection of resources
`POST`	`*.write`	Add a new resource to a collection or act on a specific resource
`UPDATE`	`*.write`	Replace a specific resource with a new value
`DELETE`	`*.write`	Remove a specific resource from a collection

Paths

Each resource on the API has a specific path. The path will always include a major version path segment, e.g., /v1/bookings.

Refer to the API Reference to learn more about each specific resource and the paths for them. We follow a RESTful scheme meaning that path segments will have collections as path segments. If a specific resource is needed, an ID segment is suffixed to the collection.

v1/bookings: Collection of bookings
v1/bookings/{id}: Specific booking

Headers

Headers are used to provide additional information to your requests and our responses. Here is a list of the most common headers and their purpose.

`Authorization`

This header contains your authentication identification. This must contain a valid bearer token for all requests that require scopes.

Authorization header with access token

Authorization: Bearer <YOUR_ACCESS_TOKEN>

Read more about this in Using the API: Authentication.

`Accept`

The Accept header is used to indicate what media type you can consume as a client. We only allow application/json in the API. We might expand the API to support multiple media types in the future, so you should always include this header in your requests to avoid interruption of service.

`Accept-Language`

The Accept-Language header is used to indicate what language or locale you want the response in. The possible values are limited by the host's configured Storefront languages. See Localization to learn more.

`User-Agent`

All API requests should include a valid User-Agent header. This header identifies the application or user making requests to the API. This is not a means of authentication but instead a way to understand the origin of requests. This will allow us to reach out to you if we see odd or dangerous behavior and usage of the API and quickly let you understand the origin of those requests.

Here are some examples of how you could structure the header.

User-Agent examples

User-Agent: My-Company-Name
User-Agent: My-Company-Name/Marketing-Automation-Script

Authentication

Most endpoints in the API require authentication. Read more about the ways to authenticate in Using the API: Authentication

Parameters

A lot of the endpoints accept parameters. These can either be required for the operation, e.g., resource IDs, or optional to modify the behavior, e.g., pagination.

Response

For every request you will receive a response confirming that the request was handled. The response's status code indicates the overall result of the request. Consult the MDN Web Docs: HTTP response status codes for more details of each status code.

In general, you can interpret the codes as;

200 - 299: Indicates that the operation was a success, e.g., 200 OK
300 - 399: Indicates that you have to continue the operation with another request, e.g., `301 Moved Permanently
400 - 499: Indicates that something was incorrect in the request, e.g., 400 Bad Request
500 - 599: Indicates that the API failed to complete your request, e.g., 500 Internal server error

Response body

All requests will return a JSON object in the response body. Refer to the specific endpoints in the API Reference to understand what properties to expect for each endpoint.

Some rules are cross-cutting however.

Timestamps are always ISO 8601 formatted as YYYY-MM-DDTHH:MM:SSZ
Failed requests (status 400 - 599) contain a standard error body with an error code and description. See Errors for details.