Custom API reference
Learn how to use the Custom API integration to import data.
The custom API integration imports data from an API, with flexible configuration options including OAuth2.
The custom API is a good option import data from a web service, including internal APIs, when a connector is not available.
🌐 Fetching and importing data
To start with, you can enter a URL (as an example, see JSON Placeholder) for your API and click import.
We'll fetch the data with a standard HTTP GET request, extract the JSON list of results, convert to newline delimited JSON and load into Gyana.
💡 If anything goes wrong, you'll get detailed debug information including information on the HTTP response and a preview of the JSON.
It is common for APIs to return a nested data structure, where the data you want is not at the top level. For example:
{
"status": "ok",
"results": 200,
"items": [
{ "userId": 1, "id": 1, ...},
{ "userId": 1, "id": 2, ...},
{ "userId": 1, "id": 3, ...},
...
]
}
Rather than try to guess, we ask you to specify the part of the JSON you need with JSON Path. The most common case will be where you want to sub-select part of the JSON by key - like in this example, where you'd need to write $.items
.
💡 JSON keys with spaces or other special characters need to use a more explicit version. For example, if the key is Item list
then the JSON Path is $.['Item list']
.
🔒 Authenticating
We support common authentication methods, including API Key, Bearer Token, Basic Auth, Digest Auth and OAuth2.
You'll be able to enter this information for your custom API, and we'll automatically set the necessary headers and query params in the request.
💡 Keys, tokens and passwords are all encrypted at rest, so only you have access to them.
OAuth2
To authenticate with an API with OAuth2, you can setup your OAuth2 connection once and re-use the connection.
Under project settings, create a new OAuth connection and name it. You'll then be prompted to provide information on the service.
To get your client ID and client secret, you'll need to register a new OAuth2 app for your service, This is usually found under the developer settings - search online if you're not sure. They'll ask you for a callback URL, which we've provided for you.
The Authorization URL and Token URL will be available somewhere in the developer documentation. Typically, they look like {service}.com/.../authorize
and {service}.com/.../token
.
Finally, you'll have to enter the scope information, essentially a list of permissions. This will be different for every provider, check the documentation for details.
If everything is correct, after you click Authorize you'll be redirected to the login page for your service, redirected back to project settings when you've logged in, and you'll see a tick for that OAuth service. You can now use this connection for any custom API.
⚡️ Customising your request
HTTP Verb
You can choose from all the HTTP verbs, including GET, POST, PUT, DELETE, ...
Query Params
You can add key/value pairs that will be appended to the URL as query params. For example, the pair key = country
, value = GB
is appended as ?country=GB
.
💡 Query params are URL encoded, e.g. +
becomes %2B
Body
We support the common options for a request body, including form-data, x-www-form-urlencoded, raw and binary.
Depending on the option, you'll be prompted to enter key/value pairs, raw text or upload files.
✏️ Example: Airtable
Airtable provides a API for each of your bases. You can use it to sync up to 100 records, ordered and filtered based on conditions you define in the URL.
Here's how to sync data with the custom API:
-
Find the URL for the table in your base. This is available in your autogenerated Airtable API documentation, and will look like
https://api.airtable.com/v0/{base}/{table}
-
Authorize the API using the "Bearer Token" option. The API key is in account settings.
-
For the JSON Path option, use
$.records[*].fields
. (We've worked this out for you, but if you want to understand where this is coming from, take a look at the raw API response.)
Your configuration page will look something like this:
After that, press Import and your data will be synced. 😊