Table of contents
- Step 1: Create an HTTP Client
- Step 2: Interacting with the HTTP client
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 Clients -> HTTP Clients and create a new HTTP Client configuration by hitting the + icon on the right upper side of the screen.
- Fill in the Name field - please note that while the identifier field is required, it will automatically be generated based on the name.
- If needed, provide a description of the HTTP Client configuration.
- If needed, disable the HTTP Client to prevent any communication from or to the system.
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
- Set request headers - Set any request headers
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
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
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.