# Quick Start

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](http://curl.haxx.se/).

### Hello World

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

```shell
$ 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](https://developer.textmaster.com/overview/authentication).

#### Using a signature

The easiest way to authenticate with TextMaster API is by using the [signature authentication strategy](https://developer.textmaster.com/overview/authentication#signature).

{% hint style="warning" %}
**Warning:** We strongly advise to use the signature strategy **only** for test purposes. Prefer using OAuth2 tokens for production use cases.
{% endhint %}

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

![](https://2001322700-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiLJk7NFk70NqFY1GU7Oi%2Fuploads%2FVTbiBp7mMUZYzEbpMgx8%2Fcreating-oauth-app-step-1.png?alt=media\&token=1f9cc0d6-5bd5-4390-8ec1-34ae2ff3c77e)

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

![](https://2001322700-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiLJk7NFk70NqFY1GU7Oi%2Fuploads%2F77HIJmzcIIAYe3cz505t%2Fcreating-oauth-app-step-2.png?alt=media\&token=a5784a2c-045b-4b31-935d-7ef12d4a81d6)

Set the following shell variables:

```shell
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:

```shell
$ 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:

```shell
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](https://developer.textmaster.com/apps/about-oauth-apps).

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](https://developer.textmaster.com/apps/building-oauth-apps/authorizing-oauth-apps#web-application-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:

![](https://2001322700-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiLJk7NFk70NqFY1GU7Oi%2Fuploads%2FPOQ7OziK6fD6Od7Wh4Zx%2Fauthorizing-oauth-app.png?alt=media\&token=7680419d-4344-41eb-9ca5-12e269dfbb74)

{% hint style="danger" %}
**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.
{% endhint %}

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](https://developer.textmaster.com/reference/projects#get-a-project) in the same way we fetched user details earlier:

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

Or, we can list our projects:

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

As the [docs](https://developer.textmaster.com/reference/projects#filter-projects) indicate, you can query a filter endpoint that can be used to filter projects returned based on various attributes:

```shell
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"
```

For more informations on the different filters available, see:

{% content-ref url="overview/filters" %}
[filters](https://developer.textmaster.com/overview/filters)
{% endcontent-ref %}

Woot! Now you know the basics of the TextMaster API!

* Signature & OAuth authentication
* Fetching and filtering projects

Dive deeper and get more details about available resources:

{% content-ref url="overview/resources-in-the-rest-api" %}
[resources-in-the-rest-api](https://developer.textmaster.com/overview/resources-in-the-rest-api)
{% endcontent-ref %}

Or, start learning about OAuth Apps:

{% content-ref url="apps/about-oauth-apps" %}
[about-oauth-apps](https://developer.textmaster.com/apps/about-oauth-apps)
{% endcontent-ref %}

Or, start exploring our API reference to get an idea of everything that's possible with the API:

{% content-ref url="reference" %}
[reference](https://developer.textmaster.com/reference)
{% endcontent-ref %}

Finally, don't forget to read about Webhooks to build or set up powerful integrations:

{% content-ref url="webhooks-and-events" %}
[webhooks-and-events](https://developer.textmaster.com/webhooks-and-events)
{% endcontent-ref %}