External APIs

External APIs allow you to fetch data from 3rd party APIs like Stripe, Asana, Zendesk, Google Sheets, Google Drive and many many more. These data sources can be used in your collections just like built-in data collections. The only drawback is that they don't support inline editing like internal collections.
​
We'll be adding a new and improved version of External APIs very soon, if you're interested please reach out to us and let us know. 
​
Wait, what's an API?
API stands for Application Programming Interface.
No no, what is an API, what does it even mean?
Put simply, an API lets two systems talk to each other. In other words, it's how you can fetch data from 3rd party applications (over the internet). For example;
Fetch a list of charges from Stripe
Fetch your latest tickets from Zendesk
Fetch you list of tasks in a given project in Asana
Fetch the files in a given Google Drive folder that start with "NOLOCO"
APIs aren't just for fetching data though, they can also be used to create, update or delete data.
For example;
Create a customer in Stripe
Create a ticket in Zendesk
Update the progress of a task in Asana
Delete a file in Google Drive
The list of things you can do with external APIs is endless, and it totally depends on what services their API supports. 
Adding a new external API
In the data tab, choose New API, from there you will need to fill out your API's details.
Adding an API will let you add one place to control the base settings for the different endpoints in the API.
What's an endpoint?
An endpoint is how you perform one of the actions as described above, so Stripe might have an API, but they'll have two different endpoints for fetching charges and creating customers. But you can store them under the same API.
To create you first API you'll need to fill in the following details;
Name
This is for your reference more than anything, usually, this is the name of the service you are integrating with, e.g. Stripe, Zendesk etc...
Base URL
This is the URL that all of your requests to this API service will start with. Most API documentation will put this in their introduction. 
For example in Stripe, it's simply https://api.stripe.com/v1/​
Headers
Add any HTTP headers in key-value form here. By default responses are setup to send and receive JSON, but if this is not the case you will have to remove those headers. 
You should also include any Authentication headers here if you need to, as this will apply to all of the endpoints you add to your API.
Authentication
If you want to use Oauth 2.0 (or if that's the only thing your APIs support - like Google's) then you can specify Oauth 2.0 Authentication here. This will bring up more required options.

OAuth callback URL
This isn't actually an input, this is the value you need to include as a callback URL in the Oauth Client options (usually in your other service providers app).
Authorization URL
This is the URL your service provider provides for authenticating your client. This is required
Access Token URL
This is the URL your service provider provides for exchanging the authorization token for an access token and a secret token. This is required.
Client ID
This is the ID provided by your service provider when you created an Oauth Client in their app.
Client Secret
This is the secret they provided to you when you created your Oauth Client. They probably only showed you this once.
Scopes
A list of scopes, separated by spaces, defining the level of access you need to request from you external service. 

Don't forget to add OAUTH2_TOKEN where appropriate in your headers. This is almost always in the Authorization header. I.e. Authorization: Bearer OAUTH2_TOKEN. This will automatically be replaced by your updated access token. 
When you have filled in all of the required fields click Save so you can add your first endpoint.
If you are using Oauth 2.0 you will then need to click Authorize. 
Adding an Endpoint to your API
An endpoint is a single URL that performs a specific action, either fetching data, updating data, creating data or deleting data in a 3rd party service. 
Endpoints in Noloco share the base URL of their API and any headers defined there. That means that any authentication required should already be handled at the API level.
To get started click the +  at the bottom of the page. There are a few required details
Name
This is so you can identify the endpoint, this might be "Fetch Charges" for example
Method
This is the HTTP method of the endpoint. It can be either GET, POST, DELETE, PUT, or PATCH.

If you are fetching data it is most likely GET. This should be in your providers API documentation.
Request type
This defines whether this endpoint simply fetches data or mutates it (updates, creates or deletes).
Endpoints that mutate data can't be used in collections, whereas endpoints that fetch data can't be used in form submissions. 
Path & Parameters
This is the unique path of the endpoint as provided by your 3rd party API. This is the value that comes after the Base URL you defined in the endpoint.
For example, to fetch charges in Stripe this is simply charges/

You can also include Variables in your path and parameters using the {{variableName}} notation.

This is useful if you need to fetch data specific to the user that's logged in. Like fetching the Asana tasks related to that users project. You will need to specify the data type and a sample value for each unique variable name below.
Headers & Authentication
As in the API settings you can add additional headers to your endpoint here. To override a header that's set at the endpoint level simply add another header with exactly the same name. 

You can also use the {{variableName}} notation to use variables in endpoint header values.
Body
The request body is typically a JSON string, it's only provided as an option on non-GET requests. You can leave it blank though. 

You can also use the {{variableName}} notation to use variables in the endpoint body.
Transformer
The response transformer, which is disabled by default, allows you to transform the response of your request with JavaScript. This allows you to filter out values you don't want or summarize lists of data and more on the server. 
Before saving your endpoint be sure to provide types and sample values for all variables (if any) and then Test your endpoint to ensure it's returning as expected. 

Last but not least, remember to click Save. 
​
FAQs
My endpoint is returning null
If you're using a transformer this usually means there's an error with the JavaScript you provided. You're probably missing a bracket or a semicolon or something simple. We don't do any validation on our end.
​
​

Formulas

Next - Users & Permissions

User Access

Last modified 9d ago

Copy link

Outline

Wait, what's an API?

No no, what is an API, what does it even mean?

Adding a new external API

Adding an Endpoint to your API

FAQs