Adonis JS Integration
The APIToolkit integration guide for AdonisJS provides a streamlined process to capture incoming traffic data. It collects request information and efficiently forwards it to the APIToolkit servers.
APIToolkit Adonisjs integration
The Adonisjs SDK integration guide for APIToolkit. It monitors incoming traffic, gathers the requests, and sends the request to the API toolkit servers.
Installation
Run the following command to install the package from your projects root:
npm install apitoolkit-adonis
Configure the adonis package using ace
After installing the apitoolkit-adonis
SDK, run the following command to
configure it in your adonis project
node ace configure apitoolkit-adonis
Register the middleware
Then add @ioc:APIToolkit
to your global middlewares list in the
start/kernel.ts
file
Server.middleware.register([
() => import("@ioc:Adonis/Core/BodyParser"),
() => import("@ioc:APIToolkit"),
]);
Configuration
To configure the sdk first create an apitoolkit.ts
file in the /conf
directory and export a apitoolkitConfig
object with the following properties
- apiKey:
required
This API key can be generated from your
- redactHeaders:
optional
This is an array of request and response headers
that should be omited by APIToolkit
- redactRequestBody:
optional
An array of request body keypaths to be
redacted (i.e should not leave your servers)
- redactResponseBody:
optional
An array of reponse body keypaths to be
redacted
- serviceVersion:
optional
A string service version to help you monitor
different versions of your deployments
- tags:
optional
An array of tags to be associated with a request
- debug:
optional
A boolean to enable debug mode (ie print debug
information)
- disable:
optional
A boolean to disable the sdk by setting it totrue
To configure, the default export of /conf/apitoolkit
should contain all
necessary properties eg:
export const apitoolkitConfig = {
apiKey: "<YOUR_API_KEY>",
};
After configuring the sdk, all incoming request will now be send to APIToolkit.
Redacting Senstive Fields and Headers
While it's possible to mark a field as redacted from the apitoolkit dashboard, this client also supports redacting at the client side.
Client side redacting means that those fields would never leave your servers at all. So you feel safer that your sensitive data only stays on your servers.
To mark fields that should be redacted, simply add them to the
conf/apitoolkit.(js,ts)
default export object. Eg:
export const apitoolkitConfig = {
apiKey: "<YOUR_API_KEY>",
redactHeaders: ["Content-Type", "Authorization", "Cookies"], // Specified headers will be redacted
redactRequestBody: ["$.credit-card.cvv", "$.credit-card.name"], // Specified request bodies fields will be redacted
redactResponseBody: ["$.message.error"], // Specified response body fields will be redacted
};
It is important to note that while the redactHeaders
config field accepts a
list of headers(case insensitive), the redactRequestBody
and
redactResponseBody
expect a list of JSONPath strings as arguments.
The choice of JSONPath was selected to allow you have great flexibility in descibing which fields within your responses are sensitive.
Also note that these list of items to be redacted will be aplied to all endpoint requests and responses on your server.
To learn more about jsonpath, please take a look at these resources:
Using apitoolkit to observe an axios based outgoing request
To monitor outgoing request, you need to first enable asyncLocalStorage in your adonisjs project by setting useAsyncLocalStorage to true in your config/app.ts
file.
export const http: ServerConfig = {
useAsyncLocalStorage: true
// other configs
}
After setting asyncLocalStorage to true, simply wrap your axios instance with the APIToolkit observeAxios function.
import Route from '@ioc:Adonis/Core/Route'
import { observeAxios } from "apitoolkit-adonis"
import axios from "axios"
const redactHeadersList = ["Content-Type", "Authorization"];
const redactRequestBodyList = ["$.body.user.name"];
const redactResponseBodyList = undefined;
Route.get('/observer', async () => {
const response = await observeAxios(axios).get(baseURL + "/user_list/active");
return {hello: "hello world"}
})
If you're making requests to endpoints which have variable urlPaths, you should include a wildcard url of the path, so that apitoolkit groups the endpoints correctly for you on the dashboard:
import { observeAxios } from "apitoolkit-adonis";
import axios from "axios";
Route.get('/observer', async () => {
const response = await observeAxios(axios, "/users/{user_id}").get(
baseURL + "/users/user1234",
);
return {hello: "hello world"}
})
There are other optional arguments you could pass on to the observe Axios function.
Example
import Route from "@ioc:Adonis/Core/Route";
import axios from "axios";
import { observeAxios } from "apitoolkit-adonis";
const redactHeadersList = ["Content-Type", "Authorization"];
const redactRequestBodyList = ["$.body.user.password"];
const redactResponseBodyList = undefined;
Route.get("/observer", async () => {
const response = await observeAxios(
axios,
"/users/{user_id}",
redactHeadersList,
redactRequestBodyList,
redactResponseBodyList,
).get(baseURL + "/users/user1234");
});
Note that you can ignore any of these arguments except the first argument which is the axios instance to observe.
For the other arguments, you can either skip them if at the end, or use undefined as a placeholder.
Reporting errors to APIToolkit
APIToolkit detects a lot of API issues automatically, but it's also valuable to report and track errors.
This helps you associate more details about the backend with a given failing request. If you've used sentry, or rollback, or bugsnag, then you're likely aware of this functionality.
To report errors, you need to first enable asyncLocalStorage in your adonisjs project by setting useAsyncLocalStorage to true in your config/app.ts file.
export const http: ServerConfig = {
useAsyncLocalStorage: true
// other configs
}
You can then start reporting errors by calling the apitoolkit reportError
` function.
import Route from "@ioc:Adonis/Core/Route";
import { reportError } from "apitoolkit-adonis";
Route.get("/observer", async () => {
try {
throw ("Error occured");
} catch (error) {
reportError(error);
}
return { hello: "world" };
});