AdonisJs SDK Guide
To integrate your AdonisJs application with APItoolkit, you need to use this SDK to monitor incoming traffic, aggregate the requests, and then send them to APItoolkit's servers. Kindly follow this guide to get started and learn about all the supported features of APItoolkit's AdonisJs SDK.
Prerequisites
Ensure you have already completed the first three steps of the onboarding guide.
Installation
Kindly run the command below to install the SDK:
npm install apitoolkit-adonis@latest
# Or
yarn add apitoolkit-adonis@latest
Tip
If you're using Adonis v5, you will need to instead install v2.2.1
of the APItoolkit Adonis SDK (i.e., [email protected]
).
Configuration
First, run the command below to configure the SDK using ace:
node ace configure apitoolkit-adonis
Then, register the middleware, like so:
Then, create an Then, create an apitoolkit-adonis
client to your global middleware list in the start/kernel.js|ts
file, like so:import server from "@adonisjs/core/services/server";
import APIToolkit from "apitoolkit-adonis";
const client = new APIToolkit();
server.use([
() => import("#middleware/container_bindings_middleware"),
() => import("#middleware/force_json_response_middleware"),
() => import("@adonisjs/cors/cors_middleware"),
() => client.middleware(),
]);
apitoolkit.js|ts
file in the /conf
directory and export the defineConfig
object with some properties, like so:import { defineConfig } from "apitoolkit-adonis";
export default defineConfig({
apiKey: "{ENTER_YOUR_API_KEY_HERE}",
debug: false,
tags: ["environment: production", "region: us-east-1"],
serviceVersion: "v2.0",
});
@ioc:APIToolkit
to your global middleware list in the start/kernel.js|ts
file, like so:Server.middleware.register([
() => import("@ioc:Adonis/Core/BodyParser"),
() => import("@ioc:APIToolkit"),
]);
apitoolkit.js|ts
file in the /conf
directory and export an apitoolkitConfig
object with some properties, like so:export const apitoolkitConfig = {
apiKey: "{ENTER_YOUR_API_KEY_HERE}",
debug: false,
tags: ["environment: production", "region: us-east-1"],
serviceVersion: "v2.0",
};
In the configuration above, only the apiKey
option is required, but you can add the following optional fields:
Option | Description |
---|---|
debug | Set to true to enable debug mode. |
tags | A list of defined tags for your services (used for grouping and filtering data on the dashboard). |
serviceVersion | A defined string version of your application (used for further debugging on the dashboard). |
disable | Set to true to disable the SDK (data monitoring will be paused). |
redactHeaders | A list of HTTP header keys to redact. |
redactResponseBody | A list of JSONPaths from the request body to redact. |
redactRequestBody | A list of JSONPaths from the response body to redact. |
Tip
The {ENTER_YOUR_API_KEY_HERE}
demo string should be replaced with the API key generated from the APItoolkit dashboard.
Redacting Sensitive Data
If you have fields that are sensitive and should not be sent to APItoolkit servers, you can mark those fields to be redacted (the fields will never leave your servers).
To mark a field for redacting via this SDK, you need to add some additional arguments to the configuration object in the conf/apitoolkit.js|ts
file with paths to the fields that should be redacted. There are three arguments you can provide to configure what gets redacted, namely:
redactHeaders
: A list of HTTP header keys.redactRequestBody
: A list of JSONPaths from the request body.redactResponseBody
: A list of JSONPaths from the response body.
JSONPath is a query language used to select and extract data from JSON files. For example, given the following sample user data JSON object:
{
"user": {
"name": "John Martha",
"email": "[email protected]",
"addresses": [
{
"street": "123 Main St",
"city": "Anytown",
"state": "CA",
"zip": "12345"
},
{
"street": "123 Main St",
"city": "Anytown",
"state": "CA",
"zip": "12345"
}
],
"credit_card": {
"number": "4111111111111111",
"expiration": "12/28",
"cvv": "123"
}
}
}
Examples of valid JSONPath expressions would be:
JSONPath | Description |
---|---|
$.user.addresses[*].zip | In this case, APItoolkit will replace the zip field in all the objects of the addresses list inside the user object with the string [CLIENT_REDACTED] . |
$.user.credit_card | In this case, APItoolkit will replace the entire credit_card object inside the user object with the string [CLIENT_REDACTED] . |
Tip
To learn more about JSONPaths, please take a look at the official docs or use this JSONPath Evaluator to validate your JSONPath expressions.
You can also use our JSON Redaction Tool to preview what the final data sent from your API to APItoolkit will look like, after redacting any given JSON object.
Here's an example of what the configuration would look like with redacted fields:
export default defineConfig({
apiKey: "{ENTER_YOUR_API_KEY_HERE}",
debug: false,
redactHeaders: ["content-type", "Authorization", "HOST"],
redactRequestBody: ["$.user.email", "$.user.addresses"],
redactResponseBody: ["$.users[*].email", "$.users[*].credit_card"],
});
Note
- The
redactHeaders
config field expects a list of case-insensitive headers as strings. - The
redactRequestBody
andredactResponseBody
config fields expect a list of JSONPaths as strings. - The list of items to be redacted will be applied to all endpoint requests and responses on your server.
Error Reporting
With APItoolkit, you can track and report different unhandled or uncaught errors, API issues, and anomalies at different parts of your application. This will help you associate more detail and context from your backend with any failing customer request.
To report errors, you need to first enable asyncLocalStorage in your AdonisJS project by setting useAsyncLocalStorage
to true
in your config/app.js|ts
file, like so:
export const http = defineConfig({
useAsyncLocalStorage: true,
// Other configs...
});
export const http: ServerConfig = {
useAsyncLocalStorage: true,
// Other configs...
}
Unhandled server exceptions will be automatically monitored by apitoolkit but you can report specific errors by using the reportError()
function, passing in the error
argument, to manually report specific errors at different parts of your application (within the context of a web request handler), like so:
import router from "@adonisjs/core/services/router";
import { reportError } from "apitoolkit-adonis";
router.get("/observer", async () => {
try {
throw "Error occurred!";
} catch (error) {
// Report the error to APItoolkit
reportError(error);
}
return { hello: "world" };
});
Monitoring Outgoing Requests
Outgoing requests are external API calls you make from your API. By default, APItoolkit monitors all requests users make from your application and they will all appear in the API Log Explorer page. However, you can separate outgoing requests from others and explore them in the Outgoing Integrations page, alongside the incoming request that triggered them.
To monitor outgoing axios-based HTTP requests from your application, you need to first, enable asyncLocalStorage in your AdonisJS project by setting useAsyncLocalStorage
to true
in your config/app.js|ts
file, like so:
export const http = defineConfig({
useAsyncLocalStorage: true,
// Other configs...
});
export const http: ServerConfig = {
useAsyncLocalStorage: true
// Other configs...
};
The monitorAxios
to the defineConfig
configuration options in the config/apitoolkit.js|ts
file, to enable global monitoring of all axios requests (for only Adonis v6), like so:import { defineConfig } from "apitoolkit-adonis";
import axios from "axios";
export default defineConfig({
apiKey: "{ENTER_YOUR_API_KEY_HERE}",
monitorAxios: axios,
});
observeAxios()
function to monitor a specific axios request within the context of a web request handler (for both Adonis v6 and v5), like so:import { observeAxios } from "apitoolkit-adonis";
import axios from "axios";
Route.get("/observer", async () => {
const response = await observeAxios(axios).get(baseURL + "/users/user1234");
return { hello: "hello world" };
});
observeAxios
function above accepts a required axios
instance and the following optional arguments:Option Description pathWildCard
The url_path
string for URLs with path parameters.redactHeaders
A list of HTTP header keys to redact. redactResponseBody
A list of JSONPaths from the request body to redact. redactRequestBody
A list of JSONPaths from the response body to redact.
Explore the AdonisJS SDK