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

Configuration

First, run the command below to configure the SDK using ace:

node ace configure apitoolkit-adonis

Then, register the middleware, 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(),
])

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",
});

Server.middleware.register([
  () => import("@ioc:Adonis/Core/BodyParser"),
  () => import("@ioc:APIToolkit"),
])

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:

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:

1. redactHeaders: A list of HTTP header keys.
2. redactRequestBody: A list of JSONPaths from the request body.
3. redactResponseBody: A list of JSONPaths from the response body.

{
  "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:

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"],
});

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...
}

import { HttpContext, ExceptionHandler } from "@adonisjs/core/http";
import { reportError } from "apitoolkit-adonis";

export default class HttpExceptionHandler extends ExceptionHandler {
  async handle(error: unknown, ctx: HttpContext) {
    return super.handle(error, ctx);
  }

  async report(error: unknown, ctx: HttpContext) {
    // Automatically report all uncaught errors to APItoolkit
    reportError(error);
    return super.report(error, ctx);
  }
}

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...
};

import { defineConfig } from "apitoolkit-adonis";
import axios from "axios";

export default defineConfig({
  apiKey: "{ENTER_YOUR_API_KEY_HERE}",
  monitorAxios: axios,
});

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" };
});