Get started
Get started

Advanced Guide to API Use

Introduction

This guide intends to remain true to Intelastel’s no-code philosophy – while many of the concepts covered here are heavily used in modern coding practices, most of them stem from common conventions – in the same way that you don’t need to be a mechanic to drive on a motorway, you should know how to interpret the road signage you see on your journey.

Being able to integrate with a third-party application may be a necessity for your no-code project. Thanks to our integration partner, Integromat, many of these functions are already available to you as modules. However there may be situations where you need a specific function carried out and none of the preset modules are suitable.

Fortunately there are a set of HTTP API modules that will allow you to make any API request (within reason!).
In this case we will just use the Integromat HTTP API modules as a convenient interface between your Intelastel application, and a third-party API.

Note: You could create webhooks that bypass the need for Integromat and directly link to the third-party API, however this will be far less flexible and may require a great deal of trial-and-error on your part to configure. For this reason we recommend using the method detailed below.

This guide assumes that you have read and tried out the Introduction to APIs guide and have a basic understanding of their purpose.

Steps

Design the function you want to create

You should have a clear idea of the purpose of this feature; including the type of data you will be inputting, modifying and returning. This is the same as any facet of your Intelastel application design, or any other Integromat scenario you may use.

Discover if the third party you wish to integrate with has an API

Their support site should have a link to their API, and to any relevant documentation. It may be called a ‘Developer API’ or similar.

Setup your Intelastel configuration

Determine what data/records you need to update or create in your application, and how they will be served; data out to Integromat via webhook, data in via an Integromat Intelastel module.
See our guide to creating webhooks in your Intelastel application:
Using Webhooks In Intelastel

 

Create the scenario in Integromat

You’ll need to add a new module, and search for HTTP.
The type of HTTP API module you need will largely be determined by the authentication required.

Read their API documentation

This step is the most important.

A good API will be fully documented, allowing users to see what requests are possible, and how to go about making them. The best ones will include example requests for you to try out and modify.

Set up authorisation

The API specification document should tell you how the API expects secure requests to be handled – this may be in the form of a username/password combination in the cURL (see below for definition); or in the header; or as a secure connection using OAuth or similar. This will determine the type of HTTP API module you need to create in your Integromat scenario.

 


Authorisation in the Header

Authorisation in the Header

 

Authorisation in the cURLAuthorisation in the cURL

Determine the endpoint

The API documentation will list each available endpoint – this is the part of the API that sends, processes and stores the data. These are categorised by type and function – a weather API may have geographic data on one endpoint and meteorological data on another for example.

Define the cURL

You will need to put in the appropriate address and any additional parameters for the module to send the request.
This is called a cURL – client Uniform Resource Locator. Don’t be put off by the name, this is just the web equivalent of writing an address on a postal envelope!

Again, the API documentation should specify the format, but you will have to work out the configuration; these will most likely be the address of the server followed by the endpoint, then any extra parameters. For some APIs the request may be included in the cURL as well.

As an example, the openWeather API directs you to send requests to the following cURL, to retrieve weather data for the Bristol, UK area:

http://api.openweathermap.org/data/2.5/weather?id=2654675&appid={PRIVATE KEY}&units=metric

Let’s break this down into the component parts:

http:// tells the API this is a HTTP request
api.openweathermap.org is the address of the weather API server
data.2.5/weather the name of the endpoint – this endpoint handles weather data
?id=2654675 the location identifier – in this case, Bristol UK
&appid={PRIVATE KEY} the unique private key used to authorise requests to the API
&units=metric specifies the format for the data to be returned – in this case, in metric measurements.

Determine the request type

As covered briefly in the previous guide, there are several types of request available. The API documentation for your third-party integration should specify what types of request are acceptable for each endpoint, and what will be returned for each request, but here is a brief overview:

Type Function Explanation
GET Retrieve data Returns information from an endpoint based on the information sent in the request
POST Send new or updated data Creates or updates data on the API endpoint, based on the information sent in the request
PUT Send new data As a POST request, but can only be used to create new data on the endpoint
DELETE Delete data Deletes data from the endpoint, as per the request

Add necessary parameters to the header

Alongside being used for some types of authentication, you may need to add parameters to the header section to tell the API what to do with the request – there may be circumstances where you need a specific function to happen and the header parameter will define these. An example may be requesting data to be returned as a .pdf file instead of as a string of data – if the API allows it, the appropriate header configuration will tell the API how to handle the request.

Add the JSON to the body

This is the most involved part of the whole process, and the nearest you will need to get to writing actual code – whilst the average code developer wouldn’t consider writing an API request as coding, for the no-code developer it can be a grey area.
Requests can be written in any language supported by the API, however as Integromat commonly uses JSON – JavaScript Object Notation – to pass data, we will focus on this method.

Note that JSON is not a coding language – whilst it is derived from the JavaScript language, it is merely a data format designed to be human-readable.

We cannot tell you what to write here, you will have to read up and follow the examples given by the documentation for the API you wish to use. Make sure you preserve the formatting and include any special characters such as curly and square brackets:


{
"weather": [
{
"id": 500,
"main": "Rain",
"description": "light rain",
"icon": "10d"
}
],
"clouds": {
"all": 38
},
"wind": {
"speed": 4.35,
"deg": 309,
"gust": 7.87
},
}

Objects

In the term ‘JSON’, the ‘O’ stands for ‘Object’ – objects are arrays of data, collected into name-value pairs, such as:


{
"id": 500,
"main": "Rain",
"description": "light rain",
"icon": "10d"
}

Where a name-value pair is:

"description": "light rain"
in the example above.

The name is the first part; “description” and the value is the second part; “light rain”.
Your API requests will be to GET (retrieve), PUT (update) and POST (create) values for a given name-value pair, or object.

Test

Trial and error and testing will be your ally here. Test the module and look at the response you get – generally the API will return an error code which should give you an indication of the issue if the module doesn’t work; and a 200 OK response if the request was successful.
Once you start getting 200 as a response, you will see the requested data returned as output bundles in the Integromat module.

Status Codes

There are many HTTP status codes – see the link at the bottom of the article for a complete list. The table below covers the codes you are most likely to encounter when configuring your API modules:

Code Name Description Diagnosis
200 OK The request was successful Data will be processed/returned
201 CREATED The request was successful and new data is created Data is created
400 BAD REQUEST There is an issue with the request Bad format or syntax
401 UNAUTHORISED Authentication is required Authentication was probably not provided, or was presented incorrectly
403 FORBIDDEN The request is valid but the server will not allow it to be carried out Often due to an error with authentication
404 NOT FOUND The resource requested could not be found A mistyped cURL address or a cURL to a nonexistent endpoint
405 METHOD NOT ALLOWED The requested method is not supported For example, attempting to update data using a GET request
500 INTERNAL SERVER ERROR A general error message No specific error can be given
503 SERVICE UNAVAILABLE The server cannot handle the request The server may be offline

Map the variables to your webhook inputs

You may need to format the data from your webhook inputs, using Integromat tool modules, but you will be able to map any variables to the body of the request – for example, the name of a client in a record in your Intelastel application can be mapped (via webhook) to a name value in an API request that updates account data.

Map the output data bundles to your Intelastel modules

As with any other Integromat module, you can map the data returned from the API module to other modules, including your Intelastel modules. Integromat includes a ‘parse JSON’ feature which will translate the data returned to bundles and arrays, to make things easier for you. You may need to run the module at least once for this to take effect.

Mapping API outputs to your Intelastel moduleĀ 

Test your new feature!

Once you have data coming into your Intelastel application, you can proceed to format it as you see fit – In the screenshot below we’ve applied a colour filter to the Temperature records as a visual aid.

See the Filtering Your Records guide for how to achieve this:
https://www.intelastel.com/tutorial/colour-code-your-records-in-the-client-view/

Semantic definitions

You may query whether this is actually stepping into the realm of coding – after all, you are putting your instructions into a formal language, obeying a specific syntax and defining the parameters needed to operate, however we think it is still on the no-code side of the fence for three reasons:

  1. You are just writing a formal set of instructions for an external module to carry out – there is little by way of decision or structure logic needed, nor are you creating and operating new resources; to use a foreign language analogy, you are just selecting and combining statements from an existing phrasebook to order something at a restuarant, rather than being asked to create new words and phrases, let alone new and original dishes.
  2. By the very same principles of instructing an API described above, you could write a recipe and ask a chef to prepare it for you – a recipe is just an instruction set, and there is little to no structured decision logic needed for this either.
  3. This method is somewhat a last-resort; between Intelastel’s features and the wealth of existing modules on Integromat, you will likely never need to delve this deep into APIs unless you need to achieve something VERY specific.

Further reading

https://en.wikipedia.org/wiki/CURL
https://en.wikipedia.org/wiki/List_of_HTTP_status_codes

Back to tutorials

Share this