REST APIs
Connect any REST API to Noloco as a read-only collection
Last updated
Connect any REST API to Noloco as a read-only collection
Last updated
You can build Noloco collections from any REST API for maximum flexibility with your data!
To setup an API collection you will first setup the base API with its URL and any necessary headers/authentication to connect to it. After this you can add GET and POST endpoints, each of which will become a Noloco collection.
First, give your API a name that is unique across the other data sources in your app. We recommend making this as descriptive as possible, for instance if you are connecting to Intercom you might call it "[My Company's] Customer Support".
Next you need to tell us the base URL of the API. This is normally provided in the documentation for the API you are connecting to and is the URL that your endpoints will all be under. It will normally look something like https://api.example.com/v1. Note that by definition an API has a single base URL - if you are trying to query multiple URLs you will need to setup an API for each.
We then need you to configure any request headers that should be included when we query your API. These are generally configured for the entire API at once but you can add additional headers on each endpoint if needed. We add a couple of these by default to make sure that data is sent and returned in JSON format so we know what to expect. All header values are encrypted after you save them, this means that when you go back to update an API in the future you cannot retrieve the raw value you previously set. You can update it with a new value at any time which we will also encrypt on save for you.
We realise that many APIs are secured and require some form of authentication to access them. If your authentication is based on some known token or password you can add an Authorization header with the required value set (as mentioned above this will be encrypted and not accessible to read in the future). We also support OAuth2 as an authentication method, toggle this on in the API options and after you have configured the OAuth service click the Authorize button to go finalise the authentication in a new window. Note you must save your API by clicking the Create button before you are able to setup the OAuth2 authentication.
After setting up this information click the save button and wait for confirmation that we have created your API as a data source. After this you are ready to start configuring your endpoints.
To add an endpoint click the + icon at the top of the endpoints list. After creating an endpoint, the endpoint editor will open for you to set it up, you can click between the different endpoints on the endpoints list to open other endpoints in the editor. You can remove endpoints by clicking on their delete button when you have them open. Your endpoints also need to be given a name, like the API name these should be unique but they only need to be unique across the other endpoints on the API. You will see that the endpoint editor is layed out across several tabs:
Configuration
Headers
Parameters
Pagination
Format
We recommend stepping through these in their order to configure your endpoints.
The configuration tab lets you tell us how to query the endpoint, we support querying by GET or by POST. If you choose POST you can setup the request body in a code editor that will appear. Please make sure that you format the request body as valid JSON.
After this we need to know where the endpoint is. You tell us this by giving us the endpoint's path. This is the relative path under the API's base URL. For example if you want to query https://api.example.com/v1/my/data and you set the API base URL as https://api.example.com/v1, you would set the endpoint's path as /my/data. Please note that because we concatenate the base URL with the endpoint's path it is important that either the base URL ends with a / or the path begins with one, otherwise it is quite likely that we will be querying the wrong URL.
The headers tab lets you configure any additional headers that are specific to the endpoint. Like the API headers these will be encrypted on save. You do not need to redefine any headers you already set at the API level, we will combine the API headers with the endpoint headers when we make requests. For most endpoints you likely won't use this tab as the global API headers are probably all you need.
The parameters tab lets you configure query parameters to be put in the URL query string when we make requests. For example if you add a parameter with key a and value b to the example endpoint we have been using, we would make a request to https://api.example.com/v1/my/data?a=b.
Most API endpoints will not return all of their data in one response, instead they normally return pages of data and someone using them needs to request the pages until they have all been exhausted. If this is the case for your API you can enable pagination on its dedicated tab. After you have enabled it you need to tell us what method your API uses to paginate data. Right now we support three different methods:
Cursor pagination
Page numbers
Offset pagination
Cursor pagination is a paging technique used by APIs by using a cursor or pointer to indicate the position of the last result retrieved, and retrieve the next set of results from that point onwards. To setup cursor pagination you need to do two things:
Tell us where the cursor is in the response from your API
Tell us where to put the value of the cursor in requests to your API
By default we assume that the cursor is just the ID of your responses (which you configure on the format tab).
If this isn't the case you can toggle this off. You then need to use the test button to get a page of data back from the API and then select the path to the cursor in the response from the dropdown we provide.
To tell us where to put the cursor in requests you need to use a {{CURSOR}} placeholder. This can go either in the request parameters or in the request body (in the case of POST requests).
Page numbers are exactly what they sound like - the request to an API has to tell the API the number of the page of data they would like in the response. These are simple to configure, you just need to put a {{PAGE}} placeholder in either the request parameters or on the request body. We will then increment this until we stop getting data. You also need to tell us the number of the first page (usually this is 0 but it might also be 1 in some cases).
Note that some APIs may require you to add a limit or pageSize parameter somewhere on the request as well.
Offset pagination is another paging technique where you specify the starting position and (optionally) number of results to retrieve for each page. This is configured similarly to page numbers, all you need to do is add an {{OFFSET}} placeholder to the request parameters or the request body (in the case of POST requests).
The format tab lets you tell us about the structure of responses you get back from the API. There are two main things you can configure here:
Where in the response body the list of records are
Where the ID field is in the records that get returned
In most cases we will actually automatically derive the location of your records in the response, however, if there is more than one array of records we will need you to tell us which to use.
You will always have to tell us the ID field and it's important that this is chosen correctly and is in fact unique.
When you have configured your API endpoint you can use the test button to make requests to it and review the data that comes back. This will be presented in a table at the bottom of the endpoint editor. You can interact with the fields in the response by clicking on them and then choosing an option from the popover that will appear.
Note that we will only show you top-level fields in this table, if the record has nested objects inside it you will need to click on the flatten button in the popover to show child fields. These will then spread into the table and you can disable any that you do not wish to include.
The disabled fields will not be synced but will still be listed on the right of the table where they can be re-enabled. You will not be able to save your endpoint until you have either flattened or removed all nested object fields from the response.
