Toolbox HTTP Client

• Introduction to Toolbox HTTP Client 🚀
• Usage 👨‍💻
  • Http Client 🤖
  • Available methods 📚
  • Request parameters 📝
    • Platform-internal requests 🔒
  • Response 📦
  • Error handling 🚨
• Conclusion 🎉

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:

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:

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:

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.