# REST API

The **Green Stack REST API** allows you to extend your Green Stack account and integrate custom solutions.

The API is crafted around [REST](https://wikipedia.org/wiki/REST) and the REST architectural style to provide developers with a stateless and language-­agnostic interface. The API leverages common HTTP verbs and response codes, OAuth2 authentication, and resource­ oriented URLs.

## Accessing the API

The root API host is `https://api.greenstack.cloud/`

You must have an active subscription for the Green Stack REST API to add new API keys and make API calls. 

### Creating a new API key

To create a new API key:

1. **Login** to the **Green Stack Console** and navigate to **Settings**
2. Select **API Keys** from the sidebar
3. Select **New Key** to create a new API key
4. Provide a **Name** for the new key and **select** the desired **permissions**
5. Select **Save** to generate the key

Once you create a key, you must pass it with the `X-Green-Stack-Key` header to authenticate every request.

```
X-Green-Stack-Key: dgf...euhsdf
```

### API endpoint documentation

The API endpoints available are documented in an [Open API](https://spec.openapis.org/oas/latest.html) spec at [https://api.greensack.dev/v1](https://go.counterbalance.io/gs-api-ref)

## HATEOS

**HATEOAS (Hypermedia as the Engine of Application State)** is a constraint of the REST application architecture that lets us use hypermedia links in the API responses that allow the client to dynamically navigate resources without prior knowledge of the API.

Green Stack REST API returns HATEOS links in resource responses by default. These links outline relative access to related resources, collections, and references. 

### Toggling HATEOS links in API responses

Links may not be necessary or appropriate for every request. Links can be removed from the response by passing the `X-Green-Stack-Suppress-Links` header and setting it to `true`

```
X-Green-Stack-Suppress-Links: true
```