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.

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.
Last modified 1mo ago