# Resources in the REST API

This describe the resources that make up the official TextMaster REST API. If you have any problems or requests, please contact [TextMaster support](mailto:support@textmaster.com).

### Version

The current version of our API is **v1**. You must explicitly request this version by appending the version number at the end of the URL.

```
https://api.textmaster.com/v1/
```

### Schema

All API access is done over HTTPS, and accessed from `https://api.textmaster.com/`. All data is sent and received as JSON.

```shell
$ curl -i https://api.textmaster.com/ping

> HTTP/1.1 200 OK
> X-Frame-Options: SAMEORIGIN
> X-XSS-Protection: 1; mode=block
> X-Content-Type-Options: nosniff
> Content-Type: application/json; charset=utf-8
> Cache-Control: no-store, must-revalidate, private, max-age=0
> X-Request-Id: f73733ca-a8be-47ba-981d-fc22ef01865f
> X-Runtime: 0.238097
> Vary: Origin
> X-MiniProfiler-Original-Cache-Control: max-age=0, private, must-revalidate
> X-MiniProfiler-Ids: uhw0tm64jxvyu121sxkc
> Set-Cookie: __profilin=p%3Dt; path=/; HttpOnly
> Transfer-Encoding: chunked

{"message":"Textmaster API at your service"}
```

All timestamps return an [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format:

```
YYYY-MM-DDTHH:MM:SSZ
```

### Environment

A sandbox environment is made available for tests and can be accessed from `https://api.textmasterstaging.com/`. It behaves the same way as the production environment.

### Parameters

Many API endpoints take optional parameters. For `GET` requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter.

```shell
curl "https://api.textmaster.com/v1/public/expertises/5f7dcc7d8b819239aff5af7c/sub_expertises?locale=en-EU"
```

In this example, the `5f7dcc7d8b819239aff5af7c` value is provided for the `:expertise_id` parameter in the path while `:locale` is passed in the query string.

For `POST`, `PATCH`, `PUT` and `DELETE` requests, parameters not included in the URL should be encoded as JSON with a `Content-Type` header set to `application/json`.

```shell
curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"my_author":{"description":"new description"}}' \
  https://api.textmaster.com/v1/clients/my_authors/5f7dcc3c8b819239aff5a391
```

### Client Errors

There are four possible types of client errors on API calls that receive request bodies:

#### Bad Request

Sending invalid JSON will result in a `400 Bad Request` response.

```
HTTP/1.1 400 Bad Request

{"errors":{"base":["Invalid Request."]}}
```

#### Method Not Allowed

Sending an unsupported HTTP verb will result in a `405 Method Not Allowed` response.

```
HTTP/1.1 405 Method Not Allowed

{"errors":{"base":["Method Not Allowed."]}}
```

#### Not Acceptable

Sending or requesting an unsupported format will result in a `406 Not Acceptable` response.

```
HTTP/1.1 406 Not Acceptable

{"errors":{"base":["Unacceptable Request."]}}
```

#### Unprocessable Entity

Sending invalid data will result in a `422 Unprocessable Entity` response.

```
HTTP/1.1 422 Unprocessable Entity

{"errors":{"base":["Error: Object could not be changed."]}}
```

### HTTP redirects

The API uses HTTP redirection where appropriate. Clients should assume that any request may result in a redirection. Receiving an HTTP redirection is *not* an error and clients should follow the redirect. Redirect responses will have a `Location` header field which contains the URI of the resource to which the client should repeat the requests.

| Status Code | Description                                                                                                                                                                                                          |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 301         | Permanent redirection. The URI you used to make the request has been superseded by the one specified in the `Location` header field. This an all future requests to this resource should be directed to the new URI. |
| 302, 307    | Temporary redirection. The request should be repeated verbatim to the URI specified in the `Location` header field but clients should continue to use the original URI for future requests.                          |

Other HTTP status codes may be used in accordance to the [HTTP 1.1 specification](https://datatracker.ietf.org/doc/html/rfc2616).

### HTTP verbs

Where possible, the API strives to use appropriate HTTP verbs for each action.

| Verb   | Description                                  |
| ------ | -------------------------------------------- |
| GET    | Used for retrieving resources.               |
| POST   | Used for creating resources.                 |
| PUT    | Used for replacing resources or collections. |
| DELETE | Used for deleting resources.                 |

### Pagination

Requests that return multiple items will be paginated to 100 items by default. You can specify further pages with the `page` parameter. For some resources, you can also set a custom page size up to 100 with the `per_page` parameter. Note that for technical reasons, not all endpoints will honour this parameter.

```shell
curl 'https://api.textmaster.com/v1/clients/projects?page=2&per_page=100'
```

Note that page numbering is 1-based and that omitting the `page` parameter will return the first page.