Toolbox HTTP Client

Introduction to Toolbox HTTP Client ๐Ÿš€

What can Toolbox HTTP Client do? As the name suggests, itโ€™s a client for HTTP requests. So, it can send HTTP requests and get responses. As simple as that ๐Ÿ˜….

It sounds like nothing special, but the absence of this feature in the Rule Engine can be a big problem. Communication with external and internal APIs is a very important requirement in any distributed system. And rule engine has a solution for this. And it is very easy to use ๐Ÿ˜Ž.

Letโ€™s dive into the details.

Usage ๐Ÿ‘จโ€๐Ÿ’ป

In a first place we use Rule Engine for any kind of data processing, alerting and other automation tasks.

Note: By the way, you can find more useful information about Rule Engine in the Rule Engine documentation.

In our case, we are using JavaScript Expressions to execute our rules, so we need to use any kind of library for communication via HTTP. As an example, we need to manage Assets, update endpoint metadata, or work with any other information from any external source. All these goals can be achieved by Toolbox HTTP Client.

Http Client ๐Ÿค–

HTTP Client is available in Rule Engine as a part of the Toolbox ๐Ÿงฐ suite. In expressions, we can get it in the following way:

const httpClient = ctx.toolbox.httpClient;

// OR get all the tools that you need in one line ๐Ÿ‘‡
const { httpClient, geo, base64, mustache, smppClient, csv } = ctx.toolbox;

Note: You can learn more about Toolbox and its tools in our documentation:
CSV Parser,
Mustache Template Engine,
More are coming soon, so stay tuned ๐Ÿ‘€.

Available methods ๐Ÿ“š

Toolbox HTTP Client provides pretty much all main HTTP methods:

Method Description Example
GET Sends a GET request to the specified URL. httpClient.get(url) or httpClient.get(url, requestOptions)
POST Sends a POST request to the specified URL. httpClient.post(url) or httpClient.post(url, requestOptions)
PUT Sends a PUT request to the specified URL. httpClient.put(url) or httpClient.put(url, requestOptions)
PATCH Sends a PATCH request to the specified URL. httpClient.patch(url) or httpClient.patch(url, requestOptions)
DELETE Sends a DELETE request to the specified URL. httpClient.delete(url) or httpClient.delete(url, requestOptions)

Note: requestOptions is an object, that is fully optional, and allows you to specify additional options for the request, such as headers, query parameters, and more.

Request parameters ๐Ÿ“

All the methods above accept a URL as a first parameter. And you can also pass an optional second parameter, which is an object containing additional options for the request.

The requestOptions object can contain the following properties:

Property Description Type Example
headers An object containing the headers for the request. Object headers: { Content-Type: "application/json" }
params An object containing the query parameters for the request. Object params: { page: 1, limit: 10 }
body The request body. Object body: { name: "John", age: 30 }
platform Is the request platform-internal Boolean platform: true

Most parameters are look familiar, but letโ€™s talk about the platform one.

Platform-internal requests ๐Ÿ”’

As in any distributed system, Kaa provides a variety of REST APIs for communication. We use these APIs in our expression scripts. The main goal of the HTTP Client is to provide a simple way to send requests to any of these or third-party APIs. When sending a request to an internal platform service, you need to set the platform parameter to true in the requestOptions object.

Consider a Rule Engine JavaScript expression that performs an HTTP request to the Assets REST API.

const httpClient = ctx.toolbox.httpClient;

const url = "/am/api/v1/assets";
const assetId = "<your-asset-id>";

const requestOptions = {
  platform: true
};

const response = httpClient.get(`${url}/${assetId}`, requestOptions);

What platform option give us? First of all, it allows you to send authenticated requests to your platform-internal services, without any additional authentication. And you can provide short URLs to those services.

Response ๐Ÿ“ฆ

After sending a request, you will get a response object. If you use any other HTTP Client, you will be familiar with it. The Response has the following structure:

Property Description Type Example
statusCode The HTTP status code of the response. Number 200
headers The HTTP headers of the response. Object { Content-Type: "application/json" }
body The response body. Object { name: "John", age: 30 }
error The error message. String "Something went wrong ๐Ÿ”ฅ"

Error handling ๐Ÿšจ

Of course, if something goes wrong, we can determine this by checking the response status code. In addition, if any error occurs during the request, the response object will contain an error property with a message describing the error.

const httpClient = ctx.toolbox.httpClient;
const url = "/am/api/v1/assets";
const assetId = "<your-asset-id>";

const requestOptions = {
    platform: true
};

const response = httpClient.get(`${url}/${assetId}`, requestOptions);

const statusCode = response.statusCode;
if (statusCode !== 200) {
    console.error(`ERROR. Status code [${statusCode}]. ${response.error}`);
    // Output: `ERROR. Status code [420]. Time to chill out! ๐Ÿง˜`
    return false;
}

return true;

Conclusion ๐ŸŽ‰

Thatโ€™s it! You now know how to use the HTTP Client in your Rule expressions. And can easily communicate with any service on your platform.

Stay tuned for more updates and improvements! And feel free to discover our other tools and services.