Quick Start

Learn the foundations for using the REST API, starting with authentication and some endpoint examples.

Let's walk through core API concepts as we tackle some everyday use cases.

Overview

Most applications will use an existing wrapper library in the language of your choice, but it's important to familiarize yourself with the underlying API HTTP methods first.

There's no easier way to kick the tires than through cURL.

Hello World

Let's start by testing our setup. Open up a command prompt and enter the following command:

$ curl https://api.textmaster.com/ping

> {"message":"Textmaster API at your service"}%

Authentication

To be honest, doing anything interesting with the TextMaster API requires authentication.

Using a signature

The easiest way to authenticate with TextMaster API is by using the signature authentication strategy.

Warning: We strongly advise to use the signature strategy only for test purposes. Prefer using OAuth2 tokens for production use cases.

In the top-bar navigation of TextMaster's application, click on API & Loop

In the left panel, copy & paste your api key and secret.

Set the following shell variables:

export APIKEY=yourApikey
export APISECRET=yourApiSecret
export DATE=$(date -u +"%Y-%m-%d %H:%M:%S")
export SIGNATURE=$(echo -n $APISECRET$DATE | openssl sha1 | sed 's/.*= //')

Verify the validity of your signature by executing the following request:

$ curl "https://api.textmaster.com/test" \
  -H "Apikey: $APIKEY" \
  -H "Date: $DATE" \
  -H "Signature: $SIGNATURE"
  
> {"message":"You sent the following headers: { HTTP_APIKEY: yourApikey, HTTP_DATE: 2022-01-20 15:25:06, HTTP_SIGNATURE: dc5b5... }. Your api key is valid. Your date is well formatted. Your signature is valid."}%

Get your own user profile

When properly authenticated, you can take advantage of the permissions associated with your account on TextMaster. For example, try getting your own user profile:

curl "https://api.textmaster.com/v1/clients/users/me" \
  -H "Apikey: $APIKEY" \
  -H "Date: $DATE" \
  -H "Signature: $SIGNATURE"

Using OAuth tokens for apps

Apps that need to read or write private information using the API on behalf of another user should use OAuth.

OAuth uses tokens. Tokens provide two big features:

Revokable access: users can revoke authorization to third party apps at any time
Limited access: users can review the specific access that a token will provide before authorizing a third party app

Tokens should be created via a web flow. An application sends users to TextMaster to log in. TextMaster then presents a dialog indicating the name of the app, as well as the level of access the app has once it's authorized by the user. After a user authorizes access, TextMaster redirects the user back to the application:

Treat OAuth tokens like passwords! Don't share them with other users or store them in insecure places. The tokens in these examples are fake and the names have been changed to protect the innocent.

Now that we've got the hang of making authenticated calls, let's move along to the Projects API.

Projects

Almost any meaningful use of the TextMaster API will involve some level of Project information. We can GET project details in the same way we fetched user details earlier:

curl "https://api.textmaster.com/v1/clients/projects/61698af48b81926d91c0f3d1" \
  -H "Apikey: $APIKEY" \
  -H "Date: $DATE" \
  -H "Signature: $SIGNATURE"

Or, we can list our projects:

curl "https://api.textmaster.com/v1/clients/projects" \
  -H "Apikey: $APIKEY" \
  -H "Date: $DATE" \
  -H "Signature: $SIGNATURE"

As the docs indicate, you can query a filter endpoint that can be used to filter projects returned based on various attributes:

curl -Gg "https://api.textmaster.com/v1/clients/projects/filter" \
  --data-urlencode 'where={"total_word_count":{"$gt":1},"language_to_code":"en","language_from_code":"fr","level_name":"premium"}' \
  --data-urlencode 'order=level_name' \
  -H "Apikey: $APIKEY" \
  -H "Date: $DATE" \
  -H "Signature: $SIGNATURE"