Data API

Routes

Overview

Routes define which operations are available on a data controller. The module provides predefined route configurations that automatically generate endpoints with the correct HTTP methods, parameter extraction, and response handling.

Default Routes

The DefaultRoutes namespace provides five built-in routes covering standard CRUD operations.

import { DefaultRoutes } from "@antelopejs/interface-data-api";

Route	Object	HTTP Method	Endpoint Pattern
Get	`DefaultRoutes.Get`	GET	`/resource/get?id=<id>`
List	`DefaultRoutes.List`	GET	`/resource/list`
New	`DefaultRoutes.New`	POST	`/resource/new`
Edit	`DefaultRoutes.Edit`	PUT	`/resource/edit?id=<id>`
Delete	`DefaultRoutes.Delete`	DELETE	`/resource/delete?id=<id>`

Use DefaultRoutes.All to include all five routes at once.

Route Configuration

Pass a route definition object to DataController to control which endpoints are created.

// All CRUD routes
@RegisterDataController()
class UserAPI extends DataController(
  User,
  DefaultRoutes.All,
  Controller("/users"),
) {
  // ...
}

// Only specific routes
@RegisterDataController()
class UserAPI extends DataController(
  User,
  {
    get: DefaultRoutes.Get,
    list: DefaultRoutes.List,
    new: DefaultRoutes.New,
  },
  Controller("/users"),
) {
  // edit and delete endpoints are not created
}

Route Details

Get

Retrieves a single record by its identifier.

Endpoint: GET /resource/get

Query Parameters:

Parameter	Required	Description
`id`	Yes	Record identifier

Example:

GET /users/get?id=user-123

Response:

{
  "_id": "user-123",
  "name": "Bob",
  "email": "[email protected]"
}

List

Retrieves multiple records with pagination, sorting, and filtering support.

Endpoint: GET /resource/list

Query Parameters:

Parameter	Required	Default	Description
`limit`	No	`10`	Maximum number of records to return
`offset`	No	`0`	Number of records to skip
`sortKey`	No	-	Field to sort by (must be marked `@Sortable`)
`sortDirection`	No	`asc`	Sort direction: `asc` or `desc`

Example:

GET /users/list?limit=10&offset=0&sortKey=name&sortDirection=asc

Response:

{
  "results": [
    { "_id": "user-123", "name": "Alice", "email": "[email protected]" },
    { "_id": "user-456", "name": "Bob", "email": "[email protected]" }
  ],
  "total": 42,
  "offset": 0,
  "limit": 10
}

New

Creates a new record. The request body must be a JSON object with the fields to set.

Endpoint: POST /resource/new

Body: JSON object with field values.

Example:

POST /users/new
Content-Type: application/json

{
  "name": "Bob",
  "email": "[email protected]",
  "password": "secure123"
}

Response:

["user-789"]

Before inserting, the insert event is triggered on any table modifiers attached to the database table.

Edit

Updates an existing record by its identifier.

Endpoint: PUT /resource/edit

Query Parameters:

Parameter	Required	Description
`id`	Yes	Record identifier

Body: JSON object with fields to update.

Example:

PUT /users/edit?id=user-123
Content-Type: application/json

{
  "name": "Robert",
  "email": "[email protected]"
}

Response:

200 OK

Before updating, the update event is triggered on any table modifiers attached to the database table.

Delete

Deletes one or more records by their identifiers.

Endpoint: DELETE /resource/delete

Query Parameters:

Parameter	Required	Description
`id`	Yes	Record identifier(s). Pass multiple `id` parameters to delete several records at once.

Example:

DELETE /users/delete?id=user-123

Response:

200 OK

Route Options with `WithOptions`

The DefaultRoutes.WithOptions function customizes route behavior by overriding query parameters or route settings.

DefaultRoutes.WithOptions(callback, options?, endpoint?)

Parameter	Description
`callback`	The route callback to customize (e.g., `DefaultRoutes.Edit`).
`options`	An object with option overrides. These values take precedence over query parameters.
`endpoint`	An optional custom endpoint path. Defaults to the route key name.

Example

const routes = {
  edit: DefaultRoutes.Edit,
  quickEdit: DefaultRoutes.WithOptions(DefaultRoutes.Edit, {
    noMandatory: "true",
  }),
};

@RegisterDataController()
class UserAPI extends DataController(User, routes, Controller("/users")) {
  // /users/edit enforces mandatory fields
  // /users/quickEdit skips mandatory field validation
}

Available Options per Route

Get:

Option	Type	Description
`index`	`string`	Use a secondary index instead of the primary key
`noForeign`	`string`	Skip foreign key resolution

List:

Option	Type	Description
`maxPage`	`number`	Maximum allowed value for `limit` (caps the page size)
`noForeign`	`boolean`	Skip foreign key resolution
`noPluck`	`boolean`	Return all database fields instead of plucked fields
`pluckMode`	`string`	Select a named pluck mode (see `@Listable`)

New:

Option	Type	Description
`noMandatory`	`string`	Skip mandatory field validation

Edit:

Option	Type	Description
`index`	`string`	Use a secondary index instead of the primary key
`noMandatory`	`string`	Skip mandatory field validation

Custom Routes

For operations beyond CRUD, define a custom route callback with func, args, and method properties.

import { Context } from "@antelopejs/interface-api";
import {
  DataController,
  DefaultRoutes,
  RegisterDataController,
} from "@antelopejs/interface-data-api";
import { Parameters } from "@antelopejs/interface-data-api/components";

const Search = {
  func: async (ctx, params) => {
    // Custom search logic
    return { results: [] };
  },
  args: [Context(), Parameters.List()],
  method: "get",
};

@RegisterDataController()
class UserAPI extends DataController(
  User,
  {
    ...DefaultRoutes.All,
    search: Search,
  },
  Controller("/users"),
) {
  // All default routes plus a custom /users/search endpoint
}

The args array contains parameter decorators that extract values from the request context. Each decorator corresponds to a parameter in the func callback, in order.

Error Handling

Default routes return standard HTTP error responses:

Status	Condition
`400 Bad Request`	Validation fails, missing required fields, or invalid parameters
`404 Not Found`	Record does not exist
`500 Internal Server Error`	Database operation fails

Error messages are returned as plain text in the response body.

Next Steps

See the access rights documentation to learn how to control field read/write permissions.

Data Controllers

Access Rights