# 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](/docs/usage/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](/apis) 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](/docs/usage/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](/docs/usage/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.


```sh 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](/docs/usage/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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status) 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](/apis) 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](/docs/usage/errors).


## See also

- [API Reference](/apis)
- [Authentication](/docs/usage/authentication)
- [Errors](/docs/usage/errors)