2.data-controllers.md

Data Controllers

Overview

A data controller is the central building block of the Data API. It connects a database table to a set of API endpoints, exposing the table fields you declare on the class. The DataController function creates a base class that combines your table definition, route definitions, and controller path into a single cohesive unit.

Create a Data Controller

Use the DataController function to define a new controller. It accepts three arguments: the table class, a route definition object, and a controller base with the endpoint path.

import { Controller } from "@antelopejs/interface-api";
import {
  DataController,
  DefaultRoutes,
  RegisterDataController,
} from "@antelopejs/interface-data-api";
import {
  Access,
  AccessMode,
  Listable,
  ModelReference,
} from "@antelopejs/interface-data-api/metadata";
import {
  BasicDataModel,
  Field,
  Index,
  Model,
  RegisterTable,
  Table,
} from "@antelopejs/interface-database-decorators";

// Define the database table
@RegisterTable("users")
class User extends Table {
  @Index({ primary: true })
  @Field("string")
  declare _id: string;

  @Field("string")
  declare email: string;

  @Field("number")
  declare age: number;
}

// Create the database model
class UserModel extends BasicDataModel(User, "users") {}

// Create the data controller
@RegisterDataController()
class UserAPI extends DataController(
  User,
  DefaultRoutes.All,
  Controller("/users"),
) {
  @ModelReference()
  @Model(UserModel, "my-database")
  declare userModel: UserModel;

  @Listable()
  @Access(AccessMode.ReadOnly)
  declare _id: string;

  @Listable()
  @Access(AccessMode.ReadWrite)
  declare email: string;

  @Access(AccessMode.ReadWrite)
  declare age: number;
}

DataController Signature

DataController(
  tableClass: typeof Table,  // Database table class
  routes: DataControllerDef, // Route definitions (e.g., DefaultRoutes.All)
  base: typeof Controller,   // Controller base with path
)

Parameter	Description
tableClass	The database table class decorated with @RegisterTable. The controller validates that this table exists in the database schema.
routes	An object mapping endpoint names to route callbacks. Use DefaultRoutes.All for standard CRUD or pass a custom subset.
base	The controller base, typically created with Controller("/path"), which sets the URL prefix for all endpoints.

Required Components

Every data controller requires the following elements:

1. Table Class - A database table decorated with @RegisterTable, defining the schema.
2. Route Definitions - Which operations to expose. Use DefaultRoutes.All or a custom selection.
3. Controller Base - The URL path prefix, created with Controller("/path").
4. Model Reference - A property decorated with @ModelReference() that holds a database model instance. This model provides the actual database operations (insert, get, update, delete).

The @RegisterDataController Decorator

Apply @RegisterDataController() to the class to finalize the controller setup. This decorator processes all field decorators, registers the defined routes, and connects parameter providers to each endpoint.

Field Declarations

Fields declared on the data controller class determine which database columns are exposed through the API. Each field can be annotated with decorators to control its behavior:

• @Access - Set read/write permissions.
• @Listable - Include the field in list responses.
• @Mandatory - Require the field on specific operations.
• @Validator - Attach a validation function.
• @Foreign - Establish a foreign key relationship.
• @Joined - Flatten a scalar field from another table onto the row.
• @Filter - Enable filtering on the field.
• @Sortable - Allow sorting by the field.

Fields without any decorator are ignored by the Data API and do not appear in API responses or accept input.

Next Steps

See the routes documentation to learn about available routes and how to customize them.