antelopejs/api

Official

A lightweight, flexible HTTP/WebSocket API module for AntelopeJS

ajs project modules add @antelopejs/api

Implementsapi

@antelopejs/api

The HTTP and WebSocket server of AntelopeJS, built on the Node.js http, https and ws servers.

Interfaces

Interface	Documentation
`@antelopejs/interface-api`	API
`@antelopejs/interface-api-util`	API Util

Controllers, routes, parameter injection, prefix and postfix handlers and WebSocket handlers are documented on the interface pages.

Install

ajs project modules add @antelopejs/api

The command writes the module's default configuration: one HTTP server on localhost:8080. In a project whose modules import @antelopejs/interface-api, ajs project modules install also adds this module when nothing implements the interface yet.

Configuration

import { defineConfig } from "@antelopejs/interface-core/config";

export default defineConfig({
  name: "my-project",
  modules: {
    api: {
      source: {
        type: "package",
        package: "@antelopejs/api",
        version: "^1.3.4",
      },
      config: {
        servers: [
          { protocol: "http", host: "localhost", port: 8080 },
          { protocol: "https", port: 8443, cert: "<pem>", key: "<pem>" },
        ],
        publicBaseUrl: "https://api.example.com",
        strictPort: false,
        autoListen: true,
        cors: {
          allowedOrigins: ["https://app.example.com", /\.example\.com$/],
          allowedMethods: ["GET", "POST", "PUT", "DELETE"],
          allowedHeaders: ["content-type", "authorization"],
          credentials: true,
          maxAge: 600,
        },
      },
    },
  },
});

Key	Default	Description
`servers`	one HTTP server on port `80`	Servers to start. Each entry takes `protocol` (`http` or `https`), optional `host` and `port`, and any Node.js `http.ServerOptions` or `https.ServerOptions`.
`publicBaseUrl`	`API_LOCAL_BASE_URL` in dev	Origin browsers use to reach the API. Required outside development: the boot fails without it.
`strictPort`	`false`	Fail instead of falling back to the next free port in development. Outside development, the module always binds the exact port.
`autoListen`	`true`	Set to `false` to create the servers without serving them until a module calls `Listen()`.
`cors`	none	CORS policy. `allowedMethods` defaults to `GET,HEAD,PUT,PATCH,POST,DELETE`, and `credentials` defaults to `true`. Change it at run time with `SetCorsConfig()`.

In development, loopback origins (localhost, 127.0.0.1, [::1], any port) pass CORS without configuration. Every other origin must be listed in allowedOrigins.

Config variables

The module publishes three config variables, all derived from the first entry of servers. Other modules read them with ${@api.<NAME>}, where api is the module's key in modules:

Variable	Value
`API_PORT`	The port the first server actually bound.
`API_LOCAL_BASE_URL`	The same-host origin, for example `http://127.0.0.1:8080`.
`API_PUBLIC_BASE_URL`	`publicBaseUrl`, without trailing slashes.

modules: {
  "file-storage-local": {
    config: { baseUrl: "${@api.API_PUBLIC_BASE_URL}" },
  },
},

The module binds its listening sockets before any other module constructs, so API_PORT is always the port the server serves.

Quick start

In the module that serves the routes, add the interface:

pnpm add @antelopejs/interface-api

Declare a controller. The module loads it on import:

import { Controller, Get, Parameter } from "@antelopejs/interface-api";

export class HelloController extends Controller("/hello") {
  @Get()
  hello(@Parameter("name", "query") name = "world") {
    return { message: `Hello ${name}` };
  }
}

export function construct(): void {}
export function destroy(): void {}
export function start(): void {}
export function stop(): void {}

Run the project with ajs project dev, then call GET http://localhost:8080/hello?name=Ada.

Documentation

API: the @antelopejs/interface-api contract this module implements
API Util: the @antelopejs/interface-api-util contract this module implements
Configuration: module sources, config blocks and config variables in antelope.config.ts

Compatibility

Package	Supported range
`@antelopejs/interface-api`	`>=0.0.14 <1.0.0`
`@antelopejs/interface-api-util`	`^0.1.2`
`@antelopejs/interface-core`	`>=0.1.1 <1.0.0`

The module is developed and tested against @antelopejs/core ^1.13.4 on Node.js 24.

Contributing

pnpm install
pnpm dev            # run the playground/ project in watch mode
pnpm lint
pnpm format:check
pnpm knip
pnpm test           # build, then ajs module test

Read the contribution guidelines before opening a pull request.

License

Apache-2.0