@antelopejs/api

The HTTP and WebSocket server module of AntelopeJS. It implements the API interfaces on the Node.js http, https, and ws servers, so the controllers and routes that other modules declare with @antelopejs/interface-api answer requests.

Part of AntelopeJS. Used by AntelopeJS DMS, the open-source back office for your PostgreSQL, MongoDB or RethinkDB database.

Interfaces

The interface pages document controllers, routes, parameter injection, prefix and postfix handlers, and WebSocket handlers.

Install

ajs project modules add @antelopejs/api

The command writes the module's default configuration, which is 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,
        },
      },
    },
  },
});

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

Config variables

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

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.

The package names the function that computes them, configVars in dist/config-vars.js, in antelopeJs.configVarsFile. A tool that reads the project without running it, such as ajs dms build, resolves ${@api.<NAME>} with that function. In that case API_PORT is the configured port, and API_PUBLIC_BASE_URL falls back to API_LOCAL_BASE_URL when publicBaseUrl is not set.

Startup gate

The module serves the port from construct on. Until the core announces that every module has started, it answers every request with 503, the body error.server_starting, and Retry-After: 1. @antelopejs/core sends that announcement as Events.ModulesStarted of @antelopejs/interface-core/modules. When the whole project starts to stop at shutdown (Events.ModulesStopping), the module answers 503 again. Stopping, reloading, or removing a single module at run time leaves the gate open.

A module that fails to start at launch leaves the project answering 503. So does a start() that has not settled after 120 seconds, which makes the start fail. Nothing runs for a request the gate holds, so a client can retry it. The module answers CORS preflights while the gate is closed, so a browser can read the 503.

GET /_live always answers 200. Use it as the liveness probe, and use a normal route as the readiness probe.

Quick start

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

pnpm add @antelopejs/interface-api

Declare a controller in the module entry. Its decorators register the routes when the module loads.

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

export class HelloController extends Controller("/greetings") {
  @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 {}

@Get() without a location uses the method name, so the route is /greetings/hello. Run the project with ajs project dev, then call GET http://localhost:8080/greetings/hello?name=Ada.

Documentation

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

Compatibility

The generated table lists @antelopejs/core, which this module requires as a peer dependency, and the interface packages it loads, with their ranges read from package.json. If another loaded module declares a range that excludes the copy this module loads, @antelopejs/core refuses to start the project. It reports Incompatible interface package resolution and names the module, its range, and the copy it found.

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