Creating an APIs

Prerequisites

Before you start creating an API, you must have first created a data table, either by importing from a spreadsheet or importing from Google Sheets.

Getting started

To begin creating an API, click APIs from the menu bar and Create API. You will need to do two things to get started:

1. Choose which data table to bind your API to. This determines what data your API returns.
2. Give your API a name. This will be used in the URL.

At this point you now have a range of other options to configure how your API behaves. The remainder of this page describes all of the different configuration options available when creating an API.

Allowing create, read, update, delete operations (CRUD)

All Sheetlabs APIs support the retrieval of records using the HTTP GET method. You can read about how your users can read from your APIs at the reading from Sheetlabs APIs documentation for consumers.

You can optionally also allow your users to write to your API. This supports the create (POST), replace (PUT), update (PATCH) and delete (DELETE) operations on records. The HTTP methods in use and their meanings are described further at RESTful support.

Caution should be taken to ensure that only authenticated and trusted users should be allowed to write data to your APIs.

To read more about how your users write to APIs, visit the writing to APIs documentation for API consumers.

Allowing searching/filtering in your APIs (GET only)

The "GET request query parameters" section of the API creation page allows you to control how users can query your API. You can elect to allow users to query the API by any of the fields that are in your underlying data table. This gives your users a simple way of searching your data.

Filters can be set for each field, allowing you granular control over how users can search your data. Each field can have the following filters applied:

Filter	Description
Disallowed	Users cannot filter results by this field.
Optional	Users may optionally supply a value for this field when calling your API.
Required	Users must supply a value for this field when calling your API.

Additionally, some field types support additional filtering options. These are:

Filter	Applicable types	Description
Partial filtering	string	Your API users will be directed to use an asterisk symbol (*) to indicate where to allow the wildcard match.
Range filtering	integer, double, datetime	Your API users will be directed to use two periods (..) between the bottom and top of a range (e.g. ?age=21..30)

To find out more about how to use the filtering when querying an API, click here.

Limiting what data is returned (GET only)

You can limit what data your API returns from GET requests in two ways.

Firstly, you can limit which fields your API returns. For example, you may wish to return product ID, it’s retail price, and the stock level, but you may not wish to include its cost price in your API response to customers!

Secondly, you can limit API to return only the top N results. An API user may optionally limit the number of results returned too, but it cannot be greater than the limit you define in the API.

Returning the Sheetlabs unique record identifier (GET only)

You can optionally have your API return the Sheetlabs unique record identifier as part of the results. This will be returned in the __id field.

This identifier is required when performing update or delete operations, so you may wish to enable the return of this field if you wish to support those operations. To read more about how the __id field is used in CRUD operations, see the writing data to APIs documentation.

Controlling access to your API

When you create your API you can restrict access to it in the following ways:

Access level	Description
Public	No access restrictions. Allow completely public/anonymous access to the API. No authentication is required to use the API at all.
Authenticated	Allow any authenticated user in your organisation access to the API. This allows you to track who is using your API. This is the default.
Group	Allow any authenticated user that is in the same group as your API to access it. The group is inherited from the data table.
Private	Only allow specified users in your organisation access to your API. You will need to select which users you wish to be able to access the API.

Documenting your API

Your API will be documented automatically for you using the descriptions that you supplied during the API creation phase. You can access documentation for your API by clicking View next to the API on the APIs page.

Code samples are provided in popular programming languages for interacting with your newly created API.

An example of a documented API can be found at https://app.sheetlabs.com/#/services/doc/ACME/getDomain.