Rest API

This page explains how to create and use custom HTTP API routes for your AthenaBot plugin.

---

Running API calls

const result = await axios.get('https://<web_api_base_ip>/api/status', {
  headers: { Authorization: '<web_api_auth_key>' }
});

Depending on the restrictions configured for each API route, the IP address of the incoming request may need to be whitelisted in your Web API configuration.

---

Adding custom API routes

1. Setting up the route file

• Create a new route file inside your plugin directory: /plugins/<plugin_name>/src/routes/

• The file name can be anything, but it is recommended to match the route name, such as hello.js.

The Web API plugin must be enabled and running for routes to work. If the Web API plugin fails to load, is disabled, or if the plugin that owns the route is disabled, the route becomes unavailable.

2. Configuration options

• name: A unique identifier for the route.

• path: The endpoint path where the route will be accessible. Do not include http:// or the domain name.

• type: The HTTP method the route should respond to. Available types: get, post, put, delete.

• ip: If enabled, all incoming requests must originate from a whitelisted IP address.

• key: If enabled, all incoming requests must include a valid authentication key in the request headers.

3. Handling requests

Each route must implement an asynchronous execute(req, res) method. This method is called whenever a request hits the registered endpoint. You can access:

• Request data via req

• Response helpers via res

Athena provides helper methods such as this.generateSuccessResponse() or this.generateErrorResponse() to keep API responses consistent across plugins.

4. Example route

The following example registers a GET endpoint at /api/hello and returns a simple JSON response.

const routeManager = require('../../../web_api/src/route.js');

module.exports = class hello extends routeManager {
  constructor(heart) {
    super(heart, { name: 'hello', path: 'api/hello', type: 'get' }, { ip: false, key: false });
  }

  async execute(req, res) {
    res.status(200).send(this.generateSuccessResponse({ message: 'Hello world!' }));
  }
};