Latest update v1.2 at 11/01/2022

Please let us know at hi@resos.com if you have questions or something you need is missing. We are extending the API as needed and per your request.

Helper libraries

API wrapper for Ruby by Tochman (unofficial)

Request limiting

All API requests are rate-limited. The current limit is 100 requests / sec, with a fixed-time reset (i.e. every minute as opposed to a minute from the first request).

All API responses will include the following headers:

Retry-After: Time in ms until reset

Authentication

Authentication to the resOS API is done using a private API key.

API key authentication is done by providing one of your private API keys in the request. You can manage your private API keys from your account settings.

Finding your API key

First ensure that the API app is enabled for your restaurant. If not, you can enable it from sidebar -> Apps. When it is enabled, head to your Settings page from the sidebar and find API credentials under the Apps category. On this page, you can view all your existing API keys and generate new ones. If none exist, simply click Generate key. The key that appears is your API key, and should be included in all requests / used for the Zapier connection.

You can also delete old API keys if you wish. Please note that any deleted keys will be invalidated, which means they will not work anymore for API requests or the Zapier integration.

Remember to keep this secret! Anyone with this key can perform all actions on resOS for your restaurant data. If used for our API, do not include this in front-end / client-side code, handle it all back-end / server-side. If you suspect that your key has been leaked, stolen or otherwise not secret anymore, you can invalidate it by going to your API credentials settings and deleting it.

The API key must be provided as the HTTP Basic Auth username in all request. No password should be provided. HTTP Basic Auth is performed by sending an Authorization header with value Basic base64(':').

E.g. for a private key:

aIcCpRKQqKPg9zVL0a7-RJt2_zx8jPq8jR20XWp_pZN

the key is base64 encoded with a tailing ":":

base64('aIcCpRKQqKPg9zVL0a7-RJt2_zx8jPq8jR20XWp_pZN:')

resulting in the value:

YUljQ3BSS1FxS1BnOXpWTDBhNy1SSnQyX3p4OGpQcThqUjIwWFdwX3BaTjo=

The complete header will be:

Authorization: Basic YUljQ3BSS1FxS1BnOXpWTDBhNy1SSnQyX3p4OGpQcThqUjIwWFdwX3BaTjo=

To test base64 encoding the following site can be used www.base64decode.org

CORS

Requests to our API will fail from the frontend due to our CORS policy. This is done for security reasons - since requests to our API require an API key, requests from the frontend would need to have your API key embedded in the code of the page, making it trivial for anyone to read and make requests on your behalf.

The proper way of calling the API from the frontend is to have a backend which relays the request and response, storing only your API key on the server backend.

Making requests

HTTPS

All requests must be made using HTTPS for security reasons. Any requests in HTTP will be rejected.

Request data

As POST and PUT data we accept application/json content-type. The content-type must be defined in the HTTP header of requests.

For GET requests query parameters are used e.g. for pagination.

Response data

All responses will be in JSON.

Pagination

Some list endpoints support pagination using skip and limit query variables, where skip defines the number or records to skip in the result and limit defined the number of records to return.

By default skip is 0 and limit is 100. Maximum number of records returned is also 100 unless defined otherwise for a specific endpoint.

E.g. to get 10 records at a time, getting records from 20 to 30:

/bookings?skip=20&limit=10

Errors

We use conventional HTTP response codes to indicate success or failure of an API request.

In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information, and codes in the 5xx range indicate an error at resOS.

Besides the status code we include an error description as a text string in the response body.

HTTP Status Codes

Besides the status code and error text, a hint to the exact problem may be included in the response.

Webhooks

We are currently working on webhooks. If you have any specific requests, needs or use-cases you'd like to see implemented, please reach out to us at dev@resos.com.

Sorting results

All endpoints that return a list can be sorted. This is done by passing a sort parameter.

Sorting by ascending takes the value 1. Descending, the value -1. All document fields can be used for sorting.

E.g. sorting by date, ascending: createdAt:1 or descending createdAt:-1.

Multiple sorting parameters can be passed, with a comma as the delimiter. The results are sorted in priority with regards to the order in which the parameters are passed. E.g. createdAt:1,updatedAt:-1.

Search expressions

Search expressions provide a powerful way to further refine the search results from the API. It supports filtering for any one or more fields as needed.

All dates should be in UTC (Coordinated Universal Time).

A search expression is passed as a header in the HTTP request. Each parameter is split by a comma.

Search expressions support the following operators:

Examples:

More than 2 people, approved status

customQuery=people>2,status:"approved"

Earlier than date, source contains google

customQuery=date<"2021-09-18",source;"google"