index.apib

FORMAT: 1A
HOST: https://rwrstats.com/api

# Running With Rifles Stats REST API

Documentation about the [Running With Rifles Stats (RWRS)](https://rwrstats.com/) REST API. [About RWRS](https://rwrstats.com/about)

::: note
The RWRS REST API is provided "as is", without warranty of any kind, express or implied.
:::

::: warning
You are **required** to mention somewhere in your project - in a visible manner - that you're using the RWRS REST API.
Not doing so may lead to a ban from using the API.
:::

## Getting a Personal Access Token

Although this API is public, a Personal Access Token is **required** to prevent abuses. To obtain a Personal Access
Token:

  1. Create an RWRS account by [signing in using your Steam account](https://rwrstats.com/sign-in)
  2. Get your Personal Access Token by heading to [your settings page](https://rwrstats.com/settings#pat)

## Sending the Personal Access Token

All endpoints needs a valid Personal Access Token, otherwise a [403](https://httpstatuses.io/403) HTTP status code
will be returned. Send this HTTP header in all of your HTTP requests along your Personal Access Token:

```http
Authorization: Token {Your Personal Access Token}
```

## Base URL

The RWRS REST API base URL is `https://rwrstats.com/api`.

::: note
Using HTTPS is mandatory or you'll encounter redirections (which may not be appreciated by your HTTP client).
:::

## Rate limiting

To prevent abuse, all resources are rate-limited. Each IP address + Personal Access Token couple is limited to **1 request per
second**. Failing to respect this rate-limiting window will lead to a [429](https://httpstatuses.io/429) HTTP status
code.

## Ban

I reserve myself the right to ban from using the API anyone who might use it in an abusive fashion. In such cases,
all requests will return a [423](https://httpstatuses.io/423) HTTP status code.

## Cache

Some resources are subject to server-side caching (i.e you'll not necessarily get the most up-to-date data from the
server). Check their respective documentation for more information.

## HTTP status codes

The HTTP response status code must be used to check if the sent request was successfully handled or not:

  - `2xx` Everything is OK. The response body will contain whatever the resource provide (check its doc)
  - `4xx` Something is wrong on the client side (e.g an input parameter validation error)
  - `5xx` There were a server error

::: note
The RWRS REST API doesn't provide internal error codes, but tries to make a meaningful use of HTTP status codes instead.
:::

## Input & output data format

Everything is [JSON](https://en.wikipedia.org/wiki/JSON) along a `Content-Type` HTTP header of `application/json`.

### Success (2xx)

The output can be different regarding the resource. Check their respective doc.

### Client error (4xx)

Typically an input parameters validation error:

```json
{
    "message": {
        "blow": "Missing required parameter in the JSON body",
        "hey": "Missing required parameter in the JSON body"
    }
}
```

In this case the `hey` and `blow` input parameters are missing.

If a query string parameter is missing or invalid, it's the same output:

```json
{
    "message": {
        "active": "Missing required parameter in the query string"
    }
}
```

May also happen in other cases, e.g when the requested resource wasn't found:

```json
{
    "message": "This thing does not exists."
}
```

### Server error (5xx)

They should not happen (exception for [503](https://httpstatuses.io/503)). If so, please [get in touch](https://rwrstats.com/feedback).

Example:

```json
{
    "message": "Error creating this thing: IndexError: out of bounds"
}
```

## Data Structures

<!-- include(data_structures/common.apib) -->
<!-- include(data_structures/users.apib) -->
<!-- include(data_structures/players.apib) -->
<!-- include(data_structures/servers.apib) -->
<!-- include(data_structures/misc.apib) -->

<!-- include(resources/servers.apib) -->
<!-- include(resources/players.apib) -->
<!-- include(resources/friends.apib) -->
<!-- include(resources/users.apib) -->
<!-- include(resources/misc.apib) -->