Resources in the REST API

Learn how to naviguate the resources provided by the TextMaster API.

This describe the resources that make up the official TextMaster REST API. If you have any problems or requests, please contact TextMaster support.

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.

$ 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 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.

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.

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.

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.

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.