Build HTTP endpoints · API · AntelopeJS Interfaces

Overview

Use @antelopejs/interface-api to declare HTTP routes, read request data, and return responses from TypeScript controllers. The same interface also declares WebSocket handlers.

This package is the contract and decorator layer, not a standalone HTTP server. Run your controllers inside an AntelopeJS module connected to an API implementation; configure that implementation's servers before calling Listen().

The examples use TypeScript's legacy decorators (experimentalDecorators: true). Keep the module's existing AntelopeJS compiler configuration; standard JavaScript decorators do not support these parameter decorators.

The framework centers around three core concepts:

Controllers organize routes under a shared base path and support hierarchical nesting.
Route decorators (@Get, @Post, @Put, @Delete) map methods to HTTP endpoints with prefix, postfix, and monitor hooks.
Parameter decorators (@Parameter, @JSONBody, @RawBody, @Context, etc.) inject request data directly into handler arguments.

Installation

pnpm add @antelopejs/interface-api

Add your first route

Import this controller from your module so its decorator runs. This example declares GET /health; it does not start a server or configure a port.

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

class HealthController extends Controller("/health") {
  @Get("")
  status() {
    return { healthy: true };
  }
}

The empty route path is deliberate: @Get() would use the method name and register /health/status. After the provider starts listening, request /health on its configured address and check for the JSON body { "healthy": true }.

Build out the endpoint

Task	Read next	Decision to make
Group endpoints and add hooks	Controllers	Choose a base path and explicit route paths.
Return a status, headers, or a stream	HTTP handling	Return a plain value or an `HTTPResult`.
Read a path, query, header, or body	Parameters	Choose one provider per argument, then add transformations.