apiary.apib

FORMAT: 1A
HOST: http://os-dev-gateway.nebo15.com:8080/

# Annon API Gateway

Annon is a configurable API gateway that acts as a reverse proxy with a plugin system. Plugins are reducing boilerplate that must be done in each service, making overall development faster. Also it stores all requests, responses and key metrics, making it easy to debug your application. Inspired by [Kong](https://getkong.org/).

It's free. Source code is available on [GitHub](https://github.com/Nebo15/annon.api).

> "Annon" translates from the Sindarin word for 'Great Door or Gate'. Sindarin is one of the many languages spoken by the immortal Elves.

Annon consist of multiple main parts:

- [Annon API Gateway](https://github.com/Nebo15/annon.api).
- [Annon Dashboard](https://github.com/Nebo15/annon.web) - UI that allows to manage Annon settings, review and analyze Requests.
- [Annon Status Pages](https://github.com/Nebo15/annon.status.web) - UI that renders APIs status pages;
- [EView](https://hex.pm/packages/eview) - hex package that allows to receive and modify client responses from Elixir application to match [Nebo #15 API Manifest](http://docs.apimanifest.apiary.io/). So your back-ends will respond in a same way as Annon does.
- [Mithril](https://github.com/Nebo15/mithril.api) - authentication and role management service.

## Goals of the Project

- Provide single easy to use API management system for medium-to-large scale applications.
- Reduce amount of work needed in other components by orchestrating common functionalities.
- Monitoring - control response time and get answer "what happened" even in a single request perspective. Provide data for in-depth analysis.
- Authorization - set authentication and authorization requirements for each resource and reject requests that do not satisfy them.
- Improve platform scalability.

## General Features

### Caching and Performance

For performance issues Annon has build-in cache manager, it will load data from DB only once, all further work will be based on this cached data.

Whenever a single node receives request that changes cached data, it's responsible to notify all other nodes in cluster about change, and they should reload configurations from DB.

Whenever new node joins to a cluster, all other nodes should drop their cache, to resolve consistency issues.

This feature is done via [skycluster](https://github.com/Nebo15/skycluster) package. All gateway nodes is connected via Erlang distribution protocol.
It support different discovery strategies:

- `kubernetes` - selecting pods via Kubernetes API;
- `gossip` - multicast UDP gossip, using a configurable port/multicast address;
- `epmd` - using standart Erlang Port Mapper Daemon.

### Request ID's

When receiving request gateway will generate unique `request_id`. It is used to log request and this request is sent to all upstream, so whole back-ends that is affected by a request will create logs with same request id's.

Optionally, you can send `X-Request-ID` header with your own request id, but you need to make sure that its length not less than 20 characters. Also, if should be unique, or you will receive error response.

### Request Logger

Annon stores all requests and responses by their unique Request ID's in a Cassandra database. You use this information to query requests and get base analytics via [Requests API](#reference/requests/collection/get-all-requests).

API consumers may provide a custom request ID by sending `X-Request-ID: <request_id>` header. Thus, your Front-End and upstream back-ends can log information with a single unique ID.

Also, idempotency plug is relying on this logs to provide idempotency guarantees for requests with same `X-Idempotency-Key: <idempotency_key>` headers.

### Monitoring

To monitor services status we will use DogStatsD integration, that will receive following metrics:

- `request.count` (counter) - [API](#reference/apis) hit rate.
- `request.size` (gauge) - HTTP `Content-Length ` request size.
- `responses.count` (counter) - same as `request.count` but sent after request dispatch and additionally tagged with `http.status`.
- `latencies.{client,gateway,upstream}` (gauge) - total request latency for a API consumer, additionally tagged with `http.status`.

All metrics have tags: `http.host`, `http.port`, `http.method`, `api.name` and `api.id` (if matches any), `request.id`. This allows to set different aggregated views on counter data.

We recommend you to try [DataDog](https://www.datadoghq.com/) for collecting and displaying performance metrics. But this is not a hard constraint, instead you can use any StatsD collector.

### Requests Idempotency

Annon guarantees that replayed requests with same `X-Idempotency-Key: <key>` and same request will get permanent response. This is useful in a financial application, where you need good protection from duplicate user actions.

### Requests Tracing

Annon supports [OpenTracing](http://opentracing.io/) in Erlang via [Otter](https://github.com/Bluehouse-Technology/otter) library. This means that by implementing OpenTracing API in other services you can trace complete request impact for each of your services.

### Management UI

![UI Screenshow](https://github.com/Nebo15/annon.web/raw/master/docs/images/ui-animated.gif)

## Installation

Annon can be installed by compiling it from sources, but we recommend you to use our pre-build Docker containers:

- [Annon API Gateway](https://hub.docker.com/r/nebo15/annon_api/);
- [Annon Dashboard](https://hub.docker.com/r/nebo15/annon.web/);
- [Annon Status Pages](https://hub.docker.com/r/nebo15/annon.status.web/);
- [Cassandra](https://hub.docker.com/r/nebo15/alpine-cassandra/).

Our containers are based on Alpine Linux wich is a security-oriented, lightweight Linux distribution based on musl libc and busybox.

### Kubernetes

You can deploy it to Kubernetes using [example configs from Annon's Infra repo](https://github.com/Nebo15/annon.infra/blob/master/kubernetes).

### Docker Compose

For local environments we provide an [example Docker Compose configuration](https://github.com/Nebo15/annon.infra/tree/master/docker-compose). You can use this one-liner to deploy all Annon components on a local machine:

`curl -L http://bit.ly/annon_compose | bash`

## Source Code Documentation

Also there are auto-generated code documentation [available here](https://nebo15.github.io/annon.api/api-reference.html#content).

## License

See [LICENSE.md](https://github.com/Nebo15/annon.api/blob/master/LICENSE.md).

# Group APIs

API is a endpoint definition for any upstream back-end. They can be extended by Annons plugins.

#### Processing Order

Notice that even truough we trying to protect you from creating overllaping API configurations, 
we can not guarantee that they always unique. API that was defined earlier will always have 
higher priority, thus after creating overlapping API it won't work, but you won't break the one 
that were working earlier.

### Pattern Matching
#### Wildcard Domains

In API request settings you can use `%` to match any substring in a request host. Eg: `%.example.com` will match `user1.example.com`.

#### API Path

In API request settings you can use `%` to match any substring in a request path. Eg: `/blog/%/comments` will match `/blog/my_post/comments` (and a `/blog/my_post/comments` since path is prefix for request).

## APIs [/apis]

### Get APIs [GET /apis{?name,limit,starting_after,ending_before}]

+ Parameters
    + name: `My API` (string, optional) - Filter APIs by their names.
    + limit: 20 (number, optional) - A limit on the number of objects to be returned, between 1 and 100. Default: 50.
    + starting_after: 56c31536a60ad644060041af (string, optional) - A cursor to fetch next page. Taken from collection response.
    + ending_before: 56c31536a60ad644060041aa (string, optional) - A cursor to fetch previous page. Taken from collection response.

+ Response 200 (application/json)
    + Attributes (Response_Collection)
        + data (array[`API__Response`])

### Create API [POST]

+ Request (application/json)
    + Attributes 
        + api (`API__Request`, required)

+ Response 201 (application/json)
    + Attributes (Response_OK)
        + meta (Response__Meta)
            + code: 201 (number)
        + data (`API__Response`)

+ Response 409 (application/json)
    + Attributes (Response_Error)
        + meta (Response__Meta)
            + code: 409 (number)
        + error (`Response__Error_DuplicateEntity`)

### Get API [GET /apis/{id}]

+ Parameters
    + id: 1 (string, required)

+ Response 200 (application/json)
    + Attributes (Response_OK)
        + data (`API__Response`)

### Update or Create API [PUT /apis/{id}]

+ Parameters
    + id: 1 (string, required)

+ Request (application/json)
    + Attributes 
        + api (`API__Request`, required)

+ Response 200 (application/json)
    + Attributes (Response_OK)
        + data (`API__Response`)

+ Response 201 (application/json)
    + Headers
    
            Location: /apis/1
            
    + Attributes (Response_OK)
        + meta (Response__Meta)
            + code: 201 (number)
        + data (`API__Response`)

### Configure API [PATCH /apis/{id}]

+ Parameters
    + id: 1 (string, required)

+ Request (application/json)
    + Attributes (object)
        + api (object) - Any of API's fields.
            + name: my_api (string, optional) - Unique name for API.

+ Response 200 (application/json)
    + Attributes (Response_OK)
        + data (`API__Response`)

### Delete API [DELETE /apis/{id}]

+ Parameters
    + id: 1 (string, required)

+ Request (application/json)
+ Response 204 (application/json)

## Plugins [/apis/{api_id}/plugins]

This is a general section that describes methods for managing API Plugins. Each plugin has it's own settings structure, their description is provided in sections below.

### Get all Plugins binded to an API [GET]

+ Parameters
    + api_id: 1 (string, required)

+ Response 200 (application/json)
    + Attributes (Response_Collection)
        + data (array[Plugin])

### Update or Bind Plugin [PUT /apis/{api_id}/plugins/{plugin_name}]

+ Parameters
    + api_id: 1 (string)
    + plugin_name: proxy (string)

+ Request (application/json)
    + Attributes 
        + plugin (`Plugin_Proxy__Request`)

+ Response 200 (application/json)
    + Attributes (Response_OK)
        + data (`Plugin_Proxy__Response`)

+ Response 201 (application/json)
    + Attributes (Response_OK)
        + meta (Response__Meta)
            + code: 201 (number)
        + data (`Plugin_Proxy__Response`)

### Unbind Plugin [DELETE /apis/{api_id}/plugins/{plugin_name}]

+ Parameters
    + api_id: 1 (string, required)
    + plugin_name: proxy (string, required)

+ Request (application/json)
+ Response 204 (application/json)

# Group Plugins

## Proxy [/apis/{api_id}/plugins/proxy]

Proxy allows:
- Send HTTP requests from API to a `upstream`.
- Modify path and trim API-related part from it.
- Add headers to upstream request (for example, to authentificate on back-end behind gateway).
- Proxy `X-Request-ID` header, so all upstream back-ends can log request state with same UUID.

### Strip Request Path

You can set `strip_api_path` setting if you want to exclude API-related prefix from upstream request.

Request Path | Proxy Path | API Path | `strip_api_path` | Upstream Request
------------ | ---------- | -------- | ------- | --------
`/api`       | `/proxy`   | `/api`   | `false` | `/proxy/api`
`/api/foo`   | `/proxy`   | `/api`   | `false` | `/proxy/api/foo`
`/api`       | `/`        | `/api`   | `false` | `/api`
`/api/foo`   | `/`        | `/api`   | `false` | `/api/foo`
`/api`       | `/proxy`   | `/api`   | `true`  | `/proxy`
`/api/foo`   | `/proxy`   | `/api`   | `true`  | `/proxy/foo`
`/api`       | `/`        | `/api`   | `true`  | `/`
`/api/foo`   | `/`        | `/api`   | `true`  | `/foo`

### Bind or Update Proxy Plugin [PUT]

+ Parameters
    + api_id: 1 (string, required) - API ID.

+ Request (application/json)
    + Attributes
        + plugin (`Plugin_Proxy__Request`)

+ Response 200 (application/json)
    + Attributes (Response_OK)
        + data (`Plugin_Proxy__Response`)

+ Response 201 (application/json)
    + Attributes (Response_OK)
        + meta (Response__Meta)
            + code: 201 (number)
        + data (`Plugin_Proxy__Response`)

## Authentication [/apis/{api_id}/plugins/auth]

This plugin authenticates API consumers by using a configured strategy.

Right now it supports two strategies:

- `jwt` - uses JSON Web Token to resolve consumer ID and scope.
- `oauth` - uses token from `Authorization: Bearer <token>` header and subsequent request to resolve consumer ID and scope via third-party provider.

### JWT Strategy

Decodes JWT tokens received from API Consumer and validates it signature by a configured secret key.
If token is invalid, appropriate error response will be send back to api consumer.

It requests `consumer_id` to be present in token itself, but Consumer `scope` can be resolved by:

1. Adding `scope` field in JWT token.
2. Subsequent request to a third-party provider.

**Warning!** JWT signature should be Base64 encoded. Some providers (for example, Auth0) already encode it for you.

#### Consumer Usage

Consumer should send `Authorization: Bearer <jwt_token>` header with his requests.

#### Subsequent requests

You can configure this strategy to resolve consumer scope by a subsequent request to a 
third-party provider, in this case GET request will be send to `url_template` 
with substituted `{consumer_id}`. Annon will expect `HTTP 200` response in following format:

```
{
  "data": {
    "user_id": "user-dsljsdflkdflj",
    "details": {
        "scope": "originator_loans:upload"
    }
  }
}
```
`$.data.user_id` will be mapped to Consumer ID.
`$.data.details.scope` will be mapped to Consumer Scope.

**OR**

```
{
  "data": {
    "consumer_id": "user-dsljsdflkdflj",
    "consumer_scope": "originator_loans:upload"
  }
}
```

If any other response is sent, Consumer will have no scopes but `X-Consumer-ID` header will be sent to upstream.

#### Auth0 Support

**Configuration**

To configure Annon copy-paste your `Client Secret` from `Clients` -> `Settings` to plugins `signature` configuration.

**Issuing a Token**

To receive an valid JWT with scopes token you must:
1. Set `app_metadata` for all your users, it should have AT LEAST one array with consumer ID:
    ``` 
    {
      "consumer_id": "my_consumer_id"
    }
    ```
    
2. (Optional) If you prefer to receive scopes from Auth0 `app_metadata` should also have scopes array:
    ```
    {
      "consumer_id": "my_consumer_id",
      "consumer_scope": "email:read email:send"
    }
    ```

    You can set default scopes in `Client` -> `Settings` -> `Advanced` -> `App Metadata`.
    
3. When authorizing consumers set correct scope to receive JWT token with `app_metadata`: `scope=openid app_metadata`.
4. Whenever you make requests to Annon, use `id_token` from Auth0 response (it's a JWT token that we need) in a `Authorization: Bearer <id_token>` header.

### oAuth Strategy

Recieves `access_token` from a `Authorization: Bearer <access_token>` header 
and sends a subsequent request to resolve Consumer ID and scopes via third-party provider (eg. [Mithril](http://docs.mithril1.apiary.io/#)). 

#### Consumer Usage

Consumer should send `Authorization: Bearer <access_token>` header with his requests.

#### Subsequent requests

GET request will be send to `url_template` with substituted `{access_token}`. 
Annon will expect `HTTP 200` response in following formats:

```
{
  "data": {
    "user_id": "user-dsljsdflkdflj",
    "details": {
        "scope": "originator_loans:upload"
    }
  }
}
```
`$.data.user_id` will be mapped to Consumer ID.
`$.data.details.scope` will be mapped to Consumer Scope.

**OR**

```
{
  "data": {
    "consumer_id": "user-dsljsdflkdflj",
    "consumer_scope": "originator_loans:upload"
  }
}
```

If any other response is sent, Consumer will not be autheticated.

### Bind or Update Authentication Plugin [PUT]

+ Parameters
    + api_id: 1 (string, required) - API ID.

+ Request (application/json)
    + Attributes
        + plugin (`Plugin_Auth__Request`)

+ Response 200 (application/json)
    + Attributes (Response_OK)
        + data (`Plugin_Auth__Response`)

+ Response 201 (application/json)
    + Attributes (Response_OK)
        + meta (Response__Meta)
            + code: 201 (number)
        + data (`Plugin_Auth__Response`)

## ACL [/apis/{api_id}/plugins/acl]

ACL allows to set scope to access certain subpaths of your API. 

Once enabled it will restrict access to all subpaths of API, and you 
need to allow access to them by whitelisting paths or path patterns.

It expects scope to be set in Auth plugin, if scope is not set, 
API consumers will receive responses `unathorized` error.

Proxy configuration consist of pattern matches on request method and path:

```
rules: [
    {methods: ["GET", "POST", "PUT", "DELETE"], path: ".*", scopes: ["request_api"]},
    {methods: ["GET"], path: "^/profiles/me", scopes: ["read_profile"]},
    {methods: ["POST", "PUT"], path: "^/profiles/me", scopes: ["update_profile"]},
    {methods: ["DELETE"], path: "^/profiles/me", scopes: ["delete_profile"]}
]
```

Path is relative to API path, so you **don't need to specify API path prefix**!

**All rules is applied in a order they were defined.**

### Bind or Update ACL Plugin [PUT]

+ Parameters
    + api_id: 1 (string, required) - API ID.

+ Request (application/json)
    + Attributes
        + plugin (`Plugin_ACL__Request`)

+ Response 200 (application/json)
    + Attributes (Response_OK)
        + data (`Plugin_ACL__Response`)

+ Response 201 (application/json)
    + Attributes (Response_OK)
        + meta (Response__Meta)
            + code: 201 (number)
        + data (`Plugin_ACL__Response`)

## Validator [/apis/{api_id}/plugins/validator]

Validator plugin allows to set a [JSON Schema](http://json-schema.org/) to validate request to a API by pattern mathching request path:

```
rules: [
    {methods: ["POST", "PUT"], path: ".*", schema: "{}"},
    {methods: ["POST"], path: "^/profiles/me", schema: "{}"}
]
```

Path is relative to API path, so you **don't need to specify API path prefix**!

**All rules is applied in a order they were defined.**

### Bind or Update Validator Plugin [PUT]

+ Parameters
    + api_id: 1 (string, required) - API ID.

+ Request (application/json)
    + Attributes
        + plugin (`Plugin_Validator__Request`)

+ Response 200 (application/json)
    + Attributes (Response_OK)
        + data (`Plugin_Validator__Response`)

+ Response 201 (application/json)
    + Attributes (Response_OK)
        + meta (Response__Meta)
            + code: 201 (number)
        + data (`Plugin_Validator__Response`)

## Idempotency [/apis/{api_id}/plugins/idempotency]

Gateway supports idempotency for safely retrying POST requests without accidentally duplicating entity. Gateway always send back the same response for requests made with the same key. 
However, you cannot use the same key with different request parameters.

To perform an idempotent request, send a POST requests with `X-Idempotency-Key: <idempotency_key>` header. `idempotency_key` can be any unique string up to 255 characters, we recommend to use UUIDs.

Enabling idempotency will increase response latency - Requests will be created synchronously to enshure read-after-write consistency.

### Bind or Update Idempotency Plugin [PUT]

+ Parameters
    + api_id: 1 (string, required) - API ID.

+ Request (application/json)
    + Attributes
        + plugin (`Plugin_Idempotency__Request`)

+ Response 200 (application/json)
    + Attributes (Response_OK)
        + data (`Plugin_Idempotency__Response`)

+ Response 201 (application/json)
    + Attributes (Response_OK)
        + meta (Response__Meta)
            + code: 201 (number)
        + data (`Plugin_Idempotency__Response`)

## IP Restriction [/apis/{api_id}/plugins/ip_restriction]

Whitelist or blacklist IP ranges from accessing an API.

You can specify matches by replacing ranges with `*`.

Rules applied in a predicted order:

* If there is an ip whitelist - block requests from IP's that not in this list.
* If IP is in blacklist and not in white list - block request.
* If IP is in blacklist and in whitelist - allow request.

### Bind or Update IP Restriction Plugin [PUT]

+ Parameters
    + api_id: 1 (string, required) - API ID.

+ Request (application/json)
    + Attributes
        + plugin (`Plugin_IP_Restriction__Request`)

+ Response 200 (application/json)
    + Attributes (Response_OK)
        + data (`Plugin_IP_Restriction__Response`)

+ Response 201 (application/json)
    + Attributes (Response_OK)
        + meta (Response__Meta)
            + code: 201 (number)
        + data (`Plugin_IP_Restriction__Response`)

## User Agent Restriction [/apis/{api_id}/plugins/ua_restriction]

Whitelist or blacklist User Agents from accessing an API.

You can specify matches by replacing ranges with `*`.

Rules applied in a predicted order:

* If there is an User Agent whitelist - block requests from User Agents that not in this list.
* If User Agent is in blacklist and not in white list - block request.
* If User Agent is in blacklist and in whitelist - allow request.

### Bind or Update User Agent Restriction Plugin [PUT]

+ Parameters
    + api_id: 1 (string, required) - API ID.

+ Request (application/json)
    + Attributes
        + plugin (`Plugin_UA_Restriction__Request`)

+ Response 200 (application/json)
    + Attributes (Response_OK)
        + data (`Plugin_UA_Restriction__Response`)

+ Response 201 (application/json)
    + Attributes (Response_OK)
        + meta (Response__Meta)
            + code: 201 (number)
        + data (`Plugin_UA_Restriction__Response`)

## CORS [/apis/{api_id}/plugins/cors]

Plugin allows to request your APIs with Cross-Origin Resource Sharing (CORS) mechanism.

When enabled requests to API will return the following headers:

On preflight (`OPTIONS`) requests:

- `Access-Control-Allow-Origin`
- `Access-Control-Allow-Credentials`
- `Access-Control-Max-Age`
- `Access-Control-Allow-Headers`
- `Access-Control-Allow-Methods`

On `GET`, `POST`, `PUT` and other requests:

- `Access-Control-Allow-Origin`
- `Access-Control-Expose-Headers`
- `Access-Control-Allow-Credentials`

### Bind or Update CORS Plugin [PUT]

+ Parameters
    + api_id: 1 (string, required) - API ID.

+ Request (application/json)
    + Attributes
        + plugin (`Plugin_CORS__Request`)

+ Response 200 (application/json)
    + Attributes (Response_OK)
        + data (`Plugin_CORS__Response`)

+ Response 201 (application/json)
    + Attributes (Response_OK)
        + meta (Response__Meta)
            + code: 201 (number)
        + data (`Plugin_CORS__Response`)

## Rate Limit [/apis/{api_id}/plugins/rate_limit]

This plugin allows you to rate limit requests from API Consumers based on `X-Consumer-ID` header returned from authorization plugins.

If consumer is not identified, rate limit won't apply to it, since it's up to you how to configure API access policy.

**This plugin is in development.**

### Bind or Update Rate Limiter Plugin [PUT]

+ Parameters
    + api_id: 1 (string, required) - API ID.

+ Request (application/json)
    + Attributes
        + plugin (`Plugin_Rate_Limit__Request`)

+ Response 200 (application/json)
    + Attributes (Response_OK)
        + data (`Plugin_Rate_Limit__Response`)

+ Response 201 (application/json)
    + Attributes (Response_OK)
        + meta (Response__Meta)
            + code: 201 (number)
        + data (`Plugin_Rate_Limit__Response`)

## Load Shedding [/apis/{api_id}/plugins/load_shedding]

This plugin allows to set requests rate limits for an API and drops requests that go over the limit.

**This plugin is in development.**

### Bind or Update Load Shedding Plugin [PUT]

+ Parameters
    + api_id: 1 (string, required) - API ID.

+ Request (application/json)
    + Attributes
        + plugin (`Plugin_Load_Shedding__Request`)

+ Response 200 (application/json)
    + Attributes (Response_OK)
        + data (`Plugin_Load_Shedding__Response`)

+ Response 201 (application/json)
    + Attributes (Response_OK)
        + meta (Response__Meta)
            + code: 201 (number)
        + data (`Plugin_Load_Shedding__Response`)

## Static Responses [/apis/{api_id}/plugins/static_responses]

This plugin allows to serve static responses to API requests, wich allows you to build some responses directly at the edge instead of forwarding them to an internal cluster.

It can be used to mock service responses or to push common responses to the edge service.

**This plugin is in development.**

### Bind or Update Static Responses Plugin [PUT]

+ Parameters
    + api_id: 1 (string, required) - API ID.

+ Request (application/json)
    + Attributes
        + plugin (`Plugin_Static_Responses__Request`)

+ Response 200 (application/json)
    + Attributes (Response_OK)
        + data (`Plugin_Static_Responses__Response`)

+ Response 201 (application/json)
    + Attributes (Response_OK)
        + meta (Response__Meta)
            + code: 201 (number)
        + data (`Plugin_Static_Responses__Response`)

# Group Requests

## Requests [/requests]

### Get all Requests [GET /requests{?idempotency_key,api_ids,status_codes,ip_addresses,limit,starting_after,ending_before}]

+ Parameters
    + `idempotency_key`: `my_idemp_key` (string, optional) - Filter Requests by idempotency key.
    + `api_ids`: `api_id1,api_id2` (string, optional) - List of API IDs to filter Requests, separated by comma.
    + `status_codes`: `200,201` (string, optional) - List of HTTP response status codes to filter Requests, separated by comma.
    + `ip_addresses`: `127.0.0.1,182.211.120.002` (string, optional) - List of IP Addresses to filter Requests, separated by comma.
    + limit: 20 (number, optional) - A limit on the number of objects to be returned, between 1 and 100. Default: 50.
    + starting_after: 56c31536a60ad644060041af (string, optional) - A cursor to fetch next page. Taken from collection response.
    + ending_before: 56c31536a60ad644060041aa (string, optional) - A cursor to fetch previous page. Taken from collection response.

+ Response 200 (application/json)
    + Attributes (Response_Collection)
        + data (array[Request])

### Get Request [GET /requests/{id}]

+ Parameters
    + id: `my_request-sfsdfjsdoqknjdnd` (string, required)

+ Response 200 (application/json)
    + Attributes (Response_Collection)
        + data (Request_Expanded)

### Delete Request [DELETE /requests/{id}]

+ Parameters
    + id: `my_request-sfsdfjsdoqknjdnd` (string, required)

+ Request (application/json)
+ Response 204 (application/json)

# Group Service Status

## Requests Metrics [/requests_metrics{?interval,api_ids}]

### Get Requests Metrics [GET]

+ Parameters
    + `interval`: `5 minute` (string, optional) - Interval for time-based aggregation of latencies data. Supports following formats: `5 minites`, `1 minute`, `1 hour, `5 hours`, `1 day`, `5 days`. Term count can be any number.
    + `api_ids`: `api_id1,api_id2` (string, optional) - List of API IDs to filter Requests, separated by comma.

+ Response 200 (application/json)
    + Attributes (Response_OK)
        + data (`Metrics`)

## Cluster Status [/cluster_status]

### Get Cluster Status [GET]

+ Response 200 (application/json)
    + Attributes (Response_OK)
        + data (`Cluster_Status`)

## APIs Status [/apis_status{?interval}]

This endpoint can be publicly available (just configure API for it).

### Get APIs Status [GET]

This endpoint returns list of disclosed APIs statuses and can be used to render service status page.

+ Parameters
    + `interval`: `5 minute` (string, optional) - Interval for time-based aggregation of latencies data. Supports following formats: `5 minites`, `1 minute`, `1 hour, `5 hours`, `1 day`, `5 days`. Term count can be any number.

+ Response 200 (application/json)
    + Attributes (Response_Collection)
        + data (array[`API_Status`])

# Group Dictionaries

## Cluster Status [/dictionaries/plugins]

### Get all Plugins [GET]

+ Response 200 (application/json)
    + Attributes (Response_Collection)
        + data (`Plugin_Dictionary_Entry`)

# Data Structures
## Responses
### `Response_Collection`
+ meta (Response__Meta, fixed-type)
+ data (array[], fixed-type)
+ paging (Response__Pagination, fixed-type)

### `Response_OK`
+ meta (Response__Meta, fixed-type)
+ data (object, fixed-type)

### `Response_Error`
+ meta (Response__Meta, fixed-type)
    + code: 400 (number)
+ error (Response__Error, fixed-type)

### `Response__Meta`
+ code: 200 (number) - HTTP response code.
+ url: http://example.com/resource (string) - URL to requested resource.
+ type (enum) - Type of data that is located in `data` attribute.
    - object (string) - `data` attribute is a JSON object.
    - list (string) - `data` attribute is a list.
+ code: 200 (number) - HTTP response code.
+ `idempotency_key`: `idemp-ssjssdjoa8308u0us0` (string, optional) - [Idempotency key](http://docs.apimanifest.apiary.io/#introduction/optional-features/idempotent-requests). Send it trough `X-Idempotency-Key` header.
+ `request_id`: `req-adasdoijasdojsda` (string) - [Request ID](http://docs.apimanifest.apiary.io/#introduction/interacting-with-api/request-id). Send it with `X-Request-ID` header.

### `Response__Error`
+ type: type_atom (string) - Atom that represents error type.
+ message: Error description (string) - Human-readable error message. This is for developers, not end-users.

### `Response__Error_DuplicateEntity`
+ type: `object_already_exists` (string) - Atom that represents error type.
+ message: This API already exists (string) - Human-readable error message. This is for developers, not end-users.

### `Response__Error_ValidationFailed`
+ type: validation_failed (string) - type of an error.
+ message: Validation failed. You can find validators description at our API Manifest: http://docs.apimanifest.apiary.io/#introduction/interacting-with-api/errors. (string)
+ invalid (array)
    + `entry_type`: `json_data_proprty` (string) - Type of error.
    + entry: $.cvv (string) - JSON Path to an invalid property.
    + rules (array)
        + rule: required (string) - String constant that represents validation rule type. List of all types can be found in [API Manifest](http://docs.apimanifest.apiary.io/#introduction/interacting-with-api/errors).
        + params (array) - Validation Parameters.

### `Response__Pagination`
+ limit: 20 (number) - A limit on the number of objects to be returned, between 1 and 100. Default: 50.
+ cursors (object)
    + `starting_after`: 56c31536a60ad644060041af (string) - A cursor for use in pagination. An object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
    + `ending_before`: 56c31536a60ad644060041aa (string) - A cursor for use in pagination. An object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
+ size: 1000 (number) - Total number of objects in collection.
+ has_more: false (boolean) - Is this collection have more data to load in the same style as last request loaded it.

## General
### `HTTP_Verb` (enum)
- POST (string)
- PUT (string)
- GET (string)
- DELETE (string)

### `Cluster_Status`
+ cluster_size: 3 (number) - Number of nodes joined to cluster.
+ cluster_strategy: `kubernetes` (enum) - Cluster formation strategy.
    - `kubernetes` (string)
    - `epmd` (string)
    - `gossip` (string)
+ nodes (array[`Cluster_Node_Status`]) - List of nodes joined to a cluster and information about them.
+ open_ports (array[number]) - List of all opened ports.
    - 80
    - 8080

### `Cluster_Node_Status`
+ name: `nonode@nohost` (string)
+ otp_release: `19` (string)
+ process_count: 656 (number)
+ process_limit: 262144 (number)
+ run_queue: 0 (number)
+ uptime: 239.873 (number) - Seconds since node VM start.

### `Metrics`
+ latencies (array[API_Latencies])
+ `status_codes` (array[`Requests_Status_Codes`])

## APIs
### `API__Request`
+ name: my_api (string, required) - Unique name for API.
+ description: `My API example` (string, optional) - Description of an API.
+ docs_url: `http://docs.annon.apiary.io/` (string, optional) - Link to the API documentation page.
+ health (`API_Health`, optional)
+ request (`API_Request__Request`, fixed-type) - Request description.
+ disclose_status: false (boolean, optional) - If `true` API status will be publically available in API Status endpoint.
+ matching_priority: 1 (number, optional) - Priority in which APIs are matched agains consumer request path. Default value is 1.

### `API_Request__Request`
+ methods (array[`HTTP_Verb`], required) - HTTP request method.
+ scheme: http (string) - HTTP request scheme. May be: `http`, `https`.
+ host: `os-dev-gateway.nebo15.com` (string, required) - DNS address of your API or its IP.
+ port: 80 (number) - Port on which your API recieves requests.
+ path: /andrew/ (string, required) - Public path to your API. Must start with `/`. All requests that start with `path` will fall onto API rules.

### `API_Embed`
+ id: 56c31536a60ad644060041af (string) - Unique ID for API.
+ name: my_api (string, required) - Unique name for API.
+ request (`API_Request__Request`, fixed-type) - Request description.

### `API__Response`
+ id: 56c31536a60ad644060041af (string) - Unique ID for API.
+ Include API__Request
+ created_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.
+ updated_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.

### `API_Status`
+ id: 56c31536a60ad644060041af (string) - Unique ID for API.
+ name: my_api (string, required) - Unique name for API.
+ description: `My API example` (string, optional) - Description of an API.
+ docs_url: `http://docs.annon.apiary.io/` (string, optional) - Link to the API documentation page.
+ health (`API_Health`)
+ metrics (object)
    + latencies (array[API_Latencies])

### `API_Health` (enum)
- `operational` (string)
- `degradated_perfomance` (string)
- `partial_outage` (string)
- `major_outage` (string)

### `API_Latencies`
+ api_id: 56c31536a60ad644060041af (string) - Unique ID for API.
+ `avg_client_request_latency`: 100 (number)
+ `avg_gateway_latency`: 2 (number)
+ `avg_upstream_latency`: 98 (number)
+ tick: `2017-04-20T19:15:00Z` (string, required) - ISO 8601 date and time in UTC timezone.

## Plugins
### Plugin
+ name: myplugin (string, required) - Plugin name
+ is_enabled: true (boolean, required) - Flag that shows that plagin is enabled or disabled.
+ settings (object, fixed-type) - Object that describes API plugin settings.
  + key: value - A key-value storage for your API plugins.

### `Plugin_Response`
+ Include Plugin
+ created_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.
+ updated_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.

### `Plugin_Dictionary_Entry`
+ name: plugin_name (string) - Plugin name
+ validation_schema: `{}` (string) - JSON schema to validate plugin settings.
+ deps (array[]) - List of plugin names this plugin depends in runtime.
+ is_system: false (boolean) - System plugins can't be configured via ManagementAPI.

## Proxy Plugin
### `Plugin_Proxy__Request`
+ name: proxy (string, required)
+ is_enabled: true (boolean, required)
+ settings (Plugin_Proxy__Settings, fixed-type)

### `Plugin_Proxy__Response`
+ Include Plugin_Proxy__Request
+ created_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.
+ updated_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.

### `Plugin_Proxy__Settings`
+ upstream (`Plugin_Proxy__Settings_Upstream`, required)
+ `preserve_host`: false (boolean, optional) - Keep HTTP HOST host header when proxying request to an upstream.
+ `strip_api_path`: false (boolean, optional) - Strip API part of path when sending request to upstream.
+ `additional_headers` (array[`Plugin_Proxy__Settings__Additional_Header`], optional) - Additional headers that should be sent to upstream.
+ `stripped_headers` (array[string], optional) - Headers that should NOT be sent to upstream.
    + `x-Unwanted-Header`

### `Plugin_Proxy__Settings__Additional_Header`
+ `X-Consumer-Header`: `header_value` (string)

### `Plugin_Proxy__Settings_Upstream`
+ scheme: https (string) - HTTP request scheme. May be: `http`, `https`, `amqp`, `ws`.
+ host: binlist.net (string) - DNS address of your upstream or its IP.
+ port: 443 (number) - Port on which your upstream recieves requests.
+ path: /json/545708 (string) - Path to your upstream API. You can omit this parameter to preserve path from original request.

## ACL Plugin
### `Plugin_ACL__Request`
+ name: acl (string, required)
+ is_enabled: true (boolean, required)
+ settings (Plugin_ACL__Settings, fixed-type)

### `Plugin_ACL__Response`
+ Include Plugin_ACL__Request
+ created_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.
+ updated_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.

### `Plugin_ACL__Settings`
+ rules (array[`Plugin_ACL__Settings_Rule`], fixed-type) - signature to decode JWT token.

### `Plugin_ACL__Settings_Rule`
+ methods (array[`HTTP_Verb`], required)
+ path: ^my_resource/ (string, required) - Regular expression on path. **Warning!** It's relative to API path.
+ scope: `request_api profile:read` (string, required) - Requied scope to request API, delimited by space.

## Validator Plugin
### `Plugin_Validator__Request`
+ name: validator (string, required)
+ is_enabled: true (boolean, required)
+ settings (Plugin_Validator__Settings, fixed-type)

### `Plugin_Validator__Response`
+ Include Plugin_Validator__Request
+ created_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.
+ updated_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.

### `Plugin_Validator__Settings`
+ rules (array[`Plugin_Validator__Settings_Rule`], fixed-type)

### `Plugin_Validator__Settings_Rule`
+ methods (array[enum], required)
    - POST (string)
    - PUT (string)
    - PATCH (string)
+ path: `^my_resource/` (string, required) - Regular expression on path. **Warning!** It's relative to API path.
+ schema: `{}` (string, required) - [JSON Schema](http://json-schema.org/) for validating request body.

## Idempotency Plugin
### `Plugin_Idempotency__Request`
+ name: idempotency (string, required)
+ is_enabled: true (boolean, required)
+ settings (`Plugin_Idempotency__Settings`, required)

### `Plugin_Idempotency__Response`
+ Include Plugin_Idempotency__Request
+ created_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.
+ updated_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.

### `Plugin_Idempotency__Settings`
+ key_ttl: 600 (number, required) - Time to live for idempotency keys. If set to `0` keys will never expire.

## IP Restrictions Plugin
### `Plugin_IP_Restriction__Request`
+ name: ip_restriction (string, required)
+ is_enabled: true (boolean, required)
+ settings (`Plugin_IP_Restriction__Settings`, fixed-type)

### `Plugin_IP_Restriction__Response`
+ Include Plugin_IP_Restriction__Request
+ created_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.
+ updated_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.

### `Plugin_IP_Restriction__Settings`
+ whitelist (array[string], fixed-type, optional) - Whitelist of IP addresses or their ranges.
    + 255.255.255.1 (string)
    + 127.0.0.* (string)
+ blacklist (array[string], fixed-type, optional) - Blacklist of IP addresses or their ranges.
    + 255.255.255.1 (string)
    + 127.0.0.* (string)

## User Agent Restriction Plugin
### `Plugin_UA_Restriction__Request`
+ name: ua_restriction (string, required)
+ is_enabled: true (boolean, required)
+ settings (`Plugin_UA_Restriction__Settings`, fixed-type)

### `Plugin_UA_Restriction__Response`
+ Include Plugin_UA_Restriction__Request
+ created_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.
+ updated_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.

### `Plugin_UA_Restriction__Settings`
+ whitelist (array[string], fixed-type, optional) - Whitelist of User Agents or patterns.
    + `Chrome*` (string)
    + `Mozilla Firefox` (string)
+ blacklist (array[string], fixed-type, optional) - Blacklist of User Agents or patterns.
    + `Google*` (string)
    + `MyBot (version 1.0)` (string)

## Authentication Plugin
### `Plugin_Auth__Request`
+ name: auth (string, required)
+ is_enabled: true (boolean, required)
+ One of
    + settings (Plugin_Auth__Settings_oAuth, fixed-type)
    + settings (Plugin_Auth__Settings_JWT, fixed-type)
    + settings (Plugin_Auth__Settings_JWTs, fixed-type)

### `Plugin_Auth__Response`
+ Include Plugin_Auth__Request
+ created_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.
+ updated_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.

### `Plugin_Auth__Settings_oAuth`
+ strategy: oauth (string, required)
+ `url_template`: `http://ec2-52-58-60-8.eu-central-1.compute.amazonaws.com:8081/0/api.svc/tokens/{access_token}` (string, required) - Inside `url_template` you can use `{access_token}` to substitle with access token in a request path.

### `Plugin_Auth__Settings_JWT`
+ strategy: jwt (string, required)
+ `third_party_resolver`: false (string, required) - Do not resolve scopes with subsequence request.
+ secret: c3VwZXJfY29vbEhhY2tlcgo= (string, required) - Base64 encoded secret to decode JWT token.
+ algorithm (enum) - Algorithm that is used to generate signature.
    - HS256 (string)
    - HS384 (string)
    - HS512 (string)

### `Plugin_Auth__Settings_JWTs`
+ strategy: jwt (string, required)
+ `third_party_resolver`: true (boolean, required) - Resolve scopes with subsequent request. 
+ `url_template`: `http://ec2-52-58-60-8.eu-central-1.compute.amazonaws.com:8081/0/api.svc/party/{consumer_id}/scopes` (string, optional) - Inside `url_template` you can use `{consumer_id}` to substitle consumer ID in a request path.
+ secret: c3VwZXJfY29vbEhhY2tlcgo= (string, required) - Base64 encoded secret to decode JWT token.
+ algorithm (enum) - Algorithm that is used to generate signature.
    - HS256 (string)
    - HS384 (string)
    - HS512 (string)

## Rate Limit Plugin
### `Plugin_Rate_Limit__Request`
+ name: rate_limit (string, required)
+ is_enabled: true (boolean, required)
+ settings (Plugin_Rate_Limit__Settings, fixed-type)

### `Plugin_Rate_Limit__Response`
+ Include Plugin_Rate_Limit__Request
+ created_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.
+ updated_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.

### `Plugin_Rate_Limit__Settings`
+ rules (array[`Plugin_Rate_Limit_Rule`], fixed-type)
+ `consumer_id_header`: `X-Consumer-ID` (string, required) - Header with Consumer unique indentified, which is used as key for counting requests count.

### `Plugin_Rate_Limit_Rule`
+ `max_request_count`: 1000 (number, required) - Maximum requests count for each API Consumer.
+ `time`: 600 (number, required) - Period time.
+ `time_unit` (enum, required) - Period time unit.
    - seconds (string)
    - minutes (string)
    - hours (string)
    - days (string)
    - weeks (string)

## CORS Plugin
### `Plugin_CORS__Request`
+ name: cors (string, required)
+ is_enabled: true (boolean, required)
+ settings (`Plugin_CORS__Settings`, required)

### `Plugin_CORS__Response`
+ Include Plugin_CORS__Request
+ created_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.
+ updated_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.

### `Plugin_CORS__Settings`
+ One of
    + origin: `*` (string, optional) - Allow all origins
    + origin: `https?.*example\d?\.com$` (string, required) - Regular expression to whitelist request origins.
    + origin (array[string], required) - List of allowed [request origins](https://www.w3.org/TR/cors/#access-control-allow-origin-response-header).
        - http://example1.com (string)
        - http://example2.com (string)
+ credentials: true (boolean, optional) - Indicates whether or not the actual request can be made using credentials. Credentials are cookies, authorization headers or TLS client certificates.
+ max_age: 1728000 (number, optional) - Indicates how long the results of a preflight request (that is the information contained in the `Access-Control-Allow-Methods` and `Access-Control-Allow-Headers` headers) can be cached.
+ headers (array[string], optional) - Whitelist of allowed request headers.
    - `Authorization` (string)
    - `Content-Type` (string)
    - `Accept` (string)
    - `Origin` (string)
    - `User-Agent` (string)
    - `DNT` (string)
    - `Cache-Control` (string)
    - `X-Mx-ReqToken` (string)
    - `Keep-Alive` (string)
    - `X-Requested-With` (string)
    - `If-Modified-Since` (string)
    - `X-CSRF-Token` (string)
+ expose (array[string], optional) - Indicates which headers can be exposed as part of the response by listing their names.
+ methods (array[string], optional) - List of allowed HTTP verbs.
    - GET (string)
    - POST (string)
    - PUT (string)
    - PATCH (string)
    - DELETE (string)
    - OPTIONS (string)

## Load Shedding Plugin
### `Plugin_Load_Shedding__Request`
+ name: load_shedding (string, required)
+ is_enabled: true (boolean, required)
+ settings (Plugin_Load_Shedding__Settings, fixed-type)

### `Plugin_Load_Shedding__Response`
+ Include Plugin_Load_Shedding__Request
+ created_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.
+ updated_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.

### `Plugin_Load_Shedding__Settings`
+ rules (array[`Plugin_Load_Shedding_Rule`], fixed-type)

### `Plugin_Load_Shedding_Rule`
+ `max_request_count`: 1000 (number, required) - Maximum requests count.
+ `time`: 600 (number, required) - Period time.
+ `time_unit` (enum, required) - Period time unit.
    - seconds (string)
    - minutes (string)

## Static Responses Plugin
### `Plugin_Static_Responses__Request`
+ name: static_responses (string, required)
+ is_enabled: true (boolean, required)
+ settings (Plugin_Static_Responses__Settings, fixed-type)

### `Plugin_Static_Responses__Response`
+ Include Plugin_Static_Responses__Request
+ created_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.
+ updated_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.

### `Plugin_Static_Responses__Settings`
+ rules (array[`Plugin_Static_Responses_Rule`], fixed-type)

### `Plugin_Static_Responses_Rule`
+ methods (array[enum], required)
    - POST (string)
    - PUT (string)
    - PATCH (string)
+ path: `^my_resource/` (string, required) - Regular expression on path. **Warning!** It's relative to API path.
+ content: `{"hello": "world"}` (string, required) - Response content.
+ content_type: `application/json` (string, required) - HTTP Content-Type for response.
+ `additional_response_headers` (array[`Plugin_Static_Responses_Rule__Response_Header`], optional) - Additional response headers. They will override default value is it's present.

### `Plugin_Static_Responses_Rule__Response_Header`
+ name: `x-my-header` (string, required)
+ value: `my_value` (string, required)

## Requests
### Request
+ id: `tl8nd5019bkendi1uadl2nqq38g69dbf` (string) - unique request identifier.
+ idempotency_key: `myidempotencykey` (string) - Idempotency Key if consumer sent it, `null` otherwise.
+ inserted_at: `2016-11-04T16:16:20.875777` (string)
+ api (`API_Embed`, optional)
+ status_code: 200 (number) - HTTP status code.
+ ip_address: `10.2.87.0` (string) - Consumer IP address.

### `Request_Expanded`
+ Include Request
+ updated_at: `2016-11-04T16:16:20.875777` (string)
+ request (object, fixed-type)
    + method: GET (string)
    + uri: /mypath (string)
    + query (object, optional) - URI query for http request if was present, otherwise - `nil`.
    + headers (object) - List of headers that was sent by consumer.
    + body (object) - JSON HTTP request body.
+ response (object, fixed-type)
    + status_code: 200 (number) - HTTP status code.
    + headers (object) - List of headers that was sent to a consumer.
    + body (object) - JSON response body that is sent to consumer.
+ latencies
    + gateway: 100 (number) - Latency in **micro**seconds.
    + upstream: 100 (number) - Latency in **micro**seconds.
    + client_request: 100 (number) - Latency in **micro**seconds.

### `Requests_Status_Codes`
+ api_id: 56c31536a60ad644060041af (string) - Unique ID for API.
+ count: 1 (number) - Count of occurances or `status_code` in a given `tick - interval` range.
+ status_code: 301 (number) - HTTP status code.
+ tick: `2017-04-20T19:15:00Z` (string, required) - ISO 8601 date and time in UTC timezone.