# APIer

*Grey Matter's real-time Spreadsheet-to-JSON transformation microservice*.

## Endpoints

| **Endpoint**                       | **Method** | **Description**                                                                                                       | **Parameters**       |
| ---------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------- | -------------------- |
| /alive                             | GET        | Simple health check route.                                                                                            | None                 |
| /configs                           | GET        | Returns APIer's current configuration.                                                                                | None                 |
| /sheets                            | GET        | Returns a list of all sheets.                                                                                         | None                 |
| /sheets/{sheet\_name or sheet\_id} | GET        | Returns a paginated JSON array of entries (rows) from the sheet referred to by the path parameter, if one exists.     | All Query Parameters |
| /sheets/all                        | GET        | Returns a list of all entries, grouped and paginated by sheet. Note, the query parameters are applied to every sheet. | max\_rows, start     |

The documentation route is disabled by default, but can be configured by setting the [DOCS\_URL](https://greymatter.gitbook.io/grey-matter-documentation/1.3/setup/platform-services/apier#DOCS_URL).

## Query Parameters

When crafting queries, follow these guidelines:

1. Column names without spaces should not be quoted.
2. String values should be quoted.
3. Column names with spaces must be quoted.
4. Column names and values are case-sensitive.
5. Python's `and`, `or` , and `not` operators replace traditional `&&`, `||` , and `!`.

### `q`

The query string to apply. The query string must be formatted according to the python eval syntax. Values should be quoted, unless non-strings. Likewise, the full range of boolean and numerical operators are available.

Example:\
`http://localhost:8000/sheets/base?q=(state=="Washington") and (date=="2020-01-31")`

{% hint style="info" %}
`date` must be represented in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.

In production it's best practice to [URL encode](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) this query string. The example is unencoded for documentation purposes.
{% endhint %}

### `cols`

Allows for partial column selection. Every column becomes a field in the returned JSON. This filter can be useful to scale the expressiveness and response size of the returned objects. Accepts both comma delimited values or individual query parameters.

Example:\
`http://localhost:8000/sheets/base?cols=date,state,fips,cases`\
`http://localhost:8000/sheets/base?cols=date&cols=state&cols=fips&cols=cases`

### `sortby`

Sorts data by provided column names. Accepts both comma delimited values or individual query parameters.

Example:\
`http://localhost:8000/sheets/base?sortby=date,state`\
`http://localhost:8000/sheets/base?sortby=date&sortby=state`

### `ascending`

Comma delimited list of integers denoting which sorting field to sort in ascending order. A non-zero value enables ascending order for the sorting filter found in the `sortby` parameter at the same index. This parameter's array length cannot exceed the length of the `sortby` array, but can be less then. Missing values will be defaulted to ascending order.

Examples:

All ascending:

* `http://localhost:8000/sheets/base?sortby=date,state`
* `http://localhost:8000/sheets/base?sortby=date,state&ascending=1`
* `http://localhost:8000/sheets/base?sortby=date,state&ascending=1,1`

All descending:\
`http://localhost:8000/sheets/base?sortby=date,state&ascending=0,0`

Mixed:\
`http://localhost:8000/sheets/base?sortby=date,state&ascending=0`

### `max_rows`

A positive non-zero integer which sets the limit on the maximum number of entries (rows) to be returned. The default is set to 100. The returned list may be smaller than the maximum, but will never be greater. When kept constant and used in combination with start, this field assists in pagination.

### `start`

A zero-indexed positive integer denoting the start position of the first entry in the returned list. When used with `max_rows`, you can seek, slice, and paginate through the data set.

Defaults to 0, since entries are stored in a zero-indexed array. Meaning the first n entries will occupy indices 0...n-1.

Examples:

First page:\
`http://localhost:8000/sheets/base?max_rows=100&start=0`

Second Page:\
`http://localhost:8000/sheets/base?max_rows=100&start=100`

One result:\
`http://localhost:8000/sheets/base?max_rows=1&start=0`