Custom API addon

With the Custom API addon, you can integrate with many APIs out-of-the-box without custom development. This enables you to reduce costs, reduce time to the finish line, and have full autonomy in configuring and using your APIs.

How to Enable It

1. Open the Building Blocks on the left sidebar of the editor
2. Search for “Custom API”
3. Drag the custom API addon onto your project to enable it
4. Create a new custom API addon and give it a name, e.g. My custom API
5. Follow the settings below to configure the addon

Let’s exemplify

A quick way to show how something works is with an example, so here’s one.

Scenario

Let’s say you want to use an API for shortening URLs, which is sold as a service by Company X, and once you buy that service, you get an API key.

The API documentation is also available and defines what requests can be done and their schema, and the schema of the response.

Let’s assume that the service expects to receive an API-key header with the key provided as authentication and that it also defines the following endpoint for shortening URLs:

POST HTTPS api.domain.com/shorten-url

That expects a Body with { url: <some-value> } and will return { shortened_url: <another-value> }.

Finally, let’s also assume that we want to export a Shortened URL data field for our result, and also be able to handle errors in a general manner.

How To Setup

1. Create a new instance of the custom API addon
2. Name it URL Shortener API
3. Click Edit Constants
4. Then Add New constant with key API-key and value the API key you got from Company X
5. Click Save, which saves and closes the constants editing pane
6. Notice the Template for the API-key constant. We will be using that later – tip: click the template value to copy to the clipboard
7. Click Add Request
8. Give it a Request Title of Shorten URL
9. Click Add Parameter, give the parameter the name URL, and set type to Text.
10. On the HTTP Request, select POST as the method
11. Select HTTPS
12. Then type the URI – api.domain.com/shorten-url
13. Now click Add Header, name it API-key, and type or paste the template from the API-key constant (e.g. {{API-key}}) on the header content input.
14. Type { “url”: “{{URL}}” } on the Body input – notice that {{URL}} is the template for the URL parameter you defined on step 9.
15. In the Response section, click Add Field and name the field Shortened URL. Select type Text
16. In the Response Action Sets, define two action sets: success, and error – this will allow us to configure a branching logic depending on the API call result
17. In the Response Parsing, click Generate to automatically populate the base parsing code. Make any necessary adjustments, such as setting the value of the Shortened URL on success.
18. Click Save to save and close your request
19. Then click Save to save your URL shortner API instance.

Next Steps

Now in the editor, you have an action called Shorten URL, as defined in step 8., that receives a URL parameter as defined in step 9., which has a success and error Action Sets.

Then, on a successful request, the data field Shortened URL, defined in step 15., will be populated with the returned data, as defined by the parsing function from step 17.

Constants

Constants are key-value pairs that you define on your Custom API addon instance, which you can use and reuse when building your requests via templates.

For example, if you define an API-key constant, you may get a {{API-key}} template, so you can in your requests just type that (with the curly brackets), and the value will automatically be populated at every request.

Use constants for storing sensitive data, such as credentials – e.g. API keys.

Requests

Title

Give your request a clear title. For example, if you use an API for fetching a country given a city, name it e.g. Get Country By City.

Your request title will be the name of the action that calls the request, and it will also appear in the error logs.

Parameters

Parameters are data that you can input to the request the moment it is executed, whereas constants are static and never change.

A request action that has parameters, will display them in the request’s action, so you can bind manual values or data fields to them.

You can define any number of parameters for your request. Here’s how:

1. When editing a request, click Add Parameter
2. Give a name to your parameter
3. Select the type of value you are expecting to receive
4. Notice the template column, which works just like the constants. These values will allow you to use parameters when setting up your HTTP Request.

HTTP Request

The HTTP Request is where you define the actual request according to the specifications of the documentation of the API you are using:

• Method (e.g. GET or POST)
• Protocol (e.g. HTTPS)
• URI (e.g. some.api.domain.com/with/some-path)
• Query Parameters – key-value pairs to send additional data on the query string
• Headers (optional) – the request headers, which may include values such as credentials, if needed
• Body (optional) – the request body, which should follow the schema from the documentation of the API you are using

URI, Headers, and Body all support using the templates from both the general API Constants and the Parameters specified for this request. Just type the Template value, and whenever the request is run, those {{values}} will be populated with their actual values.

Response

If you are not just sending data, but expect a response with data, that response needs to be parsed.

1. Data fields

Define what data fields to have as result – i.e. the data extracted from the API response

2. Action Sets

Define what Action Sets can be triggered – for branching logic depending on the result – e.g. on success or on error.

Then, define a parsing function that can handle errors and successes, extract the data from the reply, and define which Action Sets to run. You can use the Generate button to automatically populate the function based on the data fields, and Action Sets defined in step 1. and 2.

3. The parsing function

The parsing function receives two parameters:

error

• In case of an error, it will be an Object with
  • responseText – text received from the API
  • status – the HTTP error status code (4XX or 5XX)
  • statusText – the text representation of the status code, such as “OK” or “Not Found”
• If the request is successful, it would be null.

data

• In case of an error, it will be null.
• If the request was successful, it contains the response from the API.

The parsing function must return an Object with the following schema:

{
  data: {
    "Field A": "<some-value>",
    "Field B": "<some-value>",
  },
  actionSets: ['Action Set Y']
}


data – is an Object, where the keys are the Names of the Data Fields defined in step 1.

actionSets – is an Array, with one or more of the Names of the Action Sets defined in step 2. This determines what Action Sets will be run.

Actions

Each request you define will be available as an action of the same name.

When you use a request action, the parameters you defined for that request will appear so you can bind values to them.

If you have defined action sets, you will also see them in the action, so you can branch the logic based on the result. At this point, you also have access to the response values, exported as data fields with the same name.

Data Fields

Each request you define can export data fields, which hold the result value returned by the last execution of that request’s parsing function. If you run a request multiple times, those data fields will be updated each time.

The Custom API addon also exports a general status data field and a status data field per request. These status data fields are text fields with the value idle or loading.

Logs

To view the error logs, click Logs on the top bar of your Custom API addon instance.

In the Logs panel, you see a list of errors from most recent to oldest.

The error log includes relevant information, such as when it happened and what the error was.

Unbind From project

When you add the Custom API Addon to a project, it becomes bound to that project. If you want to use a Custom API addon instance on multiple projects, you need to unbind it from the project.

Then, whenever you want to use an unbound addon, you can simply add the Addon from the store to your project, and then enable the instance you wish to use from the global list.

You can find the “Unbind from Project” button at the top bar of the addon screen. Simply click it to make it available across other projects.