Connecting to a REST API

Alumio_Bot · October 10, 2022, 1:37pm

Introduction

An HTTP client represents a (remote) web service that is used to read and/or write data. Nowadays many systems are offering web services for other systems to integrate with. Alumio allows you to create these integrations using HTTP clients.

In many cases, you are required to prove that you are authorized to use a web service. This is done by various authentication methods such as (but not limited to):

Basic authentication
Bearer Token authentication
OAuth 2 authentication
Query param authentication

Alumio offers you the ability to provide these authentications to a web service when making requests, this is done through HTTP Authentications.

For this guide, we will be connecting to a public REST API, without any authentication, that returns JSON. The steps are described below.

Step 1: Create an HTTP Client

This section will explain how to set up an HTTP Client that can be used to consume one or more endpoints of a system.

Step 1a: Setting the basics

First, it is time to set up the basic information by following these steps:

Navigate to Connections → HTTP (API) and create a new HTTP Client configuration by hitting the Create + icon on the right upper left side of the screen.
The Quick Wizard will expand allowing you:
- On Step 1: Select a corresponding application you would like to interact.
- On Step 2: Input required General and Advanced information to connect to the selected application. Usually, you need to fill out authentication credentials.
- On Step 3: Finalise your HTTP Client. Once the new HTTP Client is created, you’ll navigate to the HTTP Client details page.

On the HTTP Client details page, you can add more information on:

You can change the name of the HTTP Client, set the “Disable” option to the HTTP Client to prevent any communication from or to the system and change the prototype for usage. Below the basic settings, you can see the following tabs to fill out and improve interaction with the selected application:

Plugins & Authentication - allows you to configure or select plugins and authentication from the list of created authentications.
Error Handling & Connection - contains different settings about error abortion timeline, limitations on connection timeout (up to 30 seconds) and extra choice for the response waiting.
SSL & HTTP Authentication - displays actions that can be done with SSL and Authentication.
Advanced tab (Proxies) - adds proxies and authentication for them.

Step 1b: Configuring plugins

Now that the basic information has been defined, it is time to set up the characteristics of our REST connection. Plugins enable certain behavior whenever a connection is made using this specific connection. Below follows an overview of all available plugins and what they do:

Add base URI to request - Sets a base URL that is provided to each connection made using this client. I.e. https://magentowebshop.com
Add content-length headers to request -
Add content type headers to request - Adds the content-type header to each request made using this connection.
Add host to requests - Automatically add a host to all requests going through this HTTP client.
Add path to requests - Automatically add a path to all requests going through this HTTP client.
Append request headers - Append request headers to each request made using this connection.
Cache requests - Enables caching of the request.
Decode body contents - Enables the automatic decoding of all data returned by this HTTP client.
Follow redirects - Enables Alumio to follow 301/302 redirect headers. By default this will not be done by Alumio.
Log requests - Enables logging of the HTTP requests and responses. It is advised to use the Long formatter.
Mock requests -
Rate limit based on header - Enables Alumio to adhere rate limiting if present on the API
Remove request headers - Remove any headers send from each request made using this connection.
Retry requests on failure - Retry tasks in case they fail, useful when a system is temporarily down.
Set default headers of request - Set any default request headers to each request made using this connection.
Set request headers - Set any request headers to each request made using this connection.
Store and use cookies -

There are a lot of plugins available and it can be hard to decide which are relevant to your connection. In most cases you would at least require the following plugins:

Add base URI to request
Add content type headers to request
Log requests

(Optional) Step 1c: Setting up HTTP authentications

Most systems require consumers to be authorized before a successful connection can be made. Out of the box, Alumio supports many of the authentication methods faced when building integrations.

Basic authentication - The most simple form of authentication: a username and password which are sent using the ‘Basic’ Authorization header.
Bearer Token authentication - A form of authentication where a static token is provided.
OAuth 2 authentication - The OAuth 2.0 authorization framework is a protocol that allows a user to grant applications access to the system’s protected resources, without revealing their long-term credentials. All four grand types are supported, as well as Google Oauth2.
Query param authentication - A form of authentication where the credentials are passed as a URL parameter. I.e. ?apikey=apikey123
Request authentication - A hybrid form of authentication which allows you to do a request to login, take the result and pass it with a subsequent request. May be used to implement JWT authentications or session-based authentication.
Wsse authentication - Similar to Basic Authentication it relies on a username and password, which are sent in a specialized header to perform the authentication.

Step 2: Interacting with the HTTP client

Now that you have set up the HTTP client, you can interact with it through an incoming or outgoing configuration. Incoming configurations allow you to read data from an HTTP client, while an outgoing configuration will enable you to send data to an HTTP client.

Step 2a: Creating an incoming configuration

Click here to review the general guide on incoming configurations in order to get familiar with their purpose.

First, choose the relevant subscriber prototype: HTTP Subscriber

Now it’s time to fill in the required fields and set up the connection.

Request URI - The endpoint that needs to be consumed by this configuration. I.e. /orders or /customers. Supports placeholders for dynamic endpoints.
Request Method - The request method to be used by this configuration. I.e. GET, POST, PUT. Supports placeholders for dynamic request methods.
Payload type - Alumio allows you to provide the payload sent with the requested as plain text, or encoded in a certain format. This is dependant on the web service you need to consume.
Request parameters - The request parameters can be used to pass data along with the request such as form data, GET parameters, or any other payload.
Request encoder - By default Alumio will send the data as JSON. The request encoder may be used to
HTTP Client - The HTTP Client used to set up this connection. All settings of the HTTP Client are inherited when this configuration is executed.
Input Transformer - Used to set up dynamic values that can be used within this configuration. I.e. getting today’s date, retrieving pagination from storage, or other uses.
Response decoder - Within Alumio you will always work with data in JSON. If the data is returned by the web service in a different format, please select the correct decoder so Alumio can automatically translate it to JSON.

Step 2b: Creating an outgoing configuration

Click here to review the general guide on outgoing configurations in order to get familiar with their purpose.

First, choose the relevant publisher prototype:

HTTP Publisher - Select this publisher to perform a single API call.
Chain HTTP Publisher - Select this publisher in case you need to send multiple API calls. I.e. posting orders to an ERP system, retrieving the ERP order ID, and writing the ERP order ID back to the webshop.

Now it’s time to fill in the required fields.