cygnal/doc/20.api.md

API
===

The server part exposes a public API (by default). Read from the API is always
public but writing new reports can be restricted through the use of an
API token (see the doc about deployment for more infos).

A helper script is available under `scripts/api_doc.py` to export a
documentation of the available API endpoints and usage in the current version
of the code.


### Pagination

All the API endpoints support pagination. By default, no pagination is done.
You can force pagination specifying a `page[size]` GET parameter to specify a
number of items per page and a `page[number]` GET parameter to specify the
page to return. Pages are numbered starting from zero.

For instance,

```
> GET /api/v1/reports?page[size]=10&page[number]=0
```

will return the ten first reports of the first page, which are the ten first
reports from the database.


### Filtering

#### Basic filtering

Filtering is possible in the API through the use of a `filter` GET parameter.

You can filter on a given field value using the parameter value
`filter[FIELD]=VALUE`. For instance,

```
> GET /api/v1/reports?filter[id]=1
```

will return the reports with `id` 1.

_Note:_ for fields representing a date(time), the filtering value should be
encoded according to ISO 8601.


#### Combining filters

All provided filters must be filled for an item to be returned. That is, if
you want to return all the reports of type `interrupt` with no `upvotes`, you
can use

```
> GET /api/v1/reports?filter[type]=interrupt&filter[upvotes]=0
```

If you want to make an `OR` condition, satisfying either one of the filters,
you should make two different API calls.


#### Complex filtering

You can also use more complex elaborations through the syntax
`filter[FIELD][OPERATOR]=VALUE`. The available operators are `eq` (equal,
default operator), `ne` (not equal), `gt` (greater than), `ge` (greater or
equal), `lt` (lower than) and `le` (lower or equal). For instance,

```
> GET /api/v1/reports?filter[id][ne]=1
```

will return all the reports except the one with `id` 1.

With the filters combination capability, you can use this to get all the
reports in a geographical bounding box:

```
> GET /api/v1/reports?filter[lat][gt]=LAT_MIN&filter[lat][lt]=LAT_MAX&filter[lng][gt]=LNG_MIN&filter[lng][lt]=LNG_MAX
```

All operators can have a trailing `?` to make them consider fields without
value as matching the condition as well. This means you can use something like

```
> /api/v1/reports?filter[expiration_datetime][gt?]=2018-10-18T09:06:38.538375
```

to get the all the reports with an expiration datetime in the future or no
expiration datetime, that is all currently active reports, assuming the
current datetime is `2018-10-18T09:06:38.538375`.