API

@datrix/api turns any Datrix instance into a fully-featured REST API. Drop it in as a plugin — it auto-generates CRUD routes for every schema, handles authentication, and optionally manages file uploads.

$pnpm add @datrix/api

Setup

import { defineConfig } from "@datrix/core"
import { ApiPlugin } from "@datrix/api"

export default defineConfig(() => ({
  adapter,
  schemas,
  plugins: [
    new ApiPlugin({
      prefix: "/api",        // route prefix — default: '/api'
      defaultPageSize: 25,   // default page size — default: 25
      maxPageSize: 100,      // maximum allowed page size — default: 100
      maxPopulateDepth: 5,   // max depth for nested populate — default: 5
      excludeSchemas: [],    // schemas to exclude from auto-routes — _datrix and _datrix_migrations are always excluded
      disabled: false,       // disable HTTP request handling — plugin stays loaded, schemas are still injected and migrations still run
    } satisfies ApiConfig),
  ],
}))

What gets generated

For every schema registered with Datrix, ApiPlugin generates the following routes:

The :schema segment matches the schema's table name (e.g. schema "product" → /api/products).

API helpers

Four functions are exported from @datrix/api for use in route handlers and client-side query building.

handleRequest

handleRequest(
  datrix:   IDatrix,   // initialized Datrix instance
  request: Request,  // Web API Request
): Promise<Response>

The main entry point. Validates that ApiPlugin is registered, then routes the request to the appropriate handler (auth, CRUD, or upload). All error handling is built in — always returns a Response, never throws.

toWebRequest

toWebRequest(req: NodeIncomingRequest): Request

Converts a Node.js-style incoming request to a Web API Request. Works with Express, Fastify, Koa, and raw http.IncomingMessage — duck-typed, no framework dependency.

sendWebResponse

sendWebResponse(
  res:      NodeOutgoingResponse,
  response: Response,
): Promise<void>

Writes a Web API Response back into a Node.js-style outgoing response. Sets status code, headers, and body.

queryToParams

queryToParams<T extends DatrixEntry = DatrixRecord>(
  query: ParsedQuery<T> | undefined,
): string

Serializes a typed query object into a URL query string. Use this on the client side to build requests — it accepts the same ParsedQuery shape the server parses, so client and server stay in sync. See CRUD for usage examples.

Request handling

import { handleRequest } from "@datrix/api"

Next.js App Router

Create a catch-all route at app/api/[model]/[[...datrix]]/route.ts:

import datrix from "@/datrix.config"
import { handleRequest } from "@datrix/api"

async function handler(request: Request): Promise<Response> {
  return handleRequest(await datrix(), request)
}

export const GET    = handler
export const POST   = handler
export const PATCH  = handler
export const PUT    = handler
export const DELETE = handler

Express

Express uses Node.js IncomingMessage/ServerResponse instead of the Web Request/Response API. Use the built-in toWebRequest and sendWebResponse helpers to bridge them — no extra dependencies required.

import express from "express"
import datrix from "./datrix.config"
import { handleRequest, toWebRequest, sendWebResponse } from "@datrix/api"

const app = express()
app.use(express.raw({ type: "*/*" }))  // preserve body as Buffer

app.all("*", async (req, res) => {
  const request  = toWebRequest(req)
  const response = await handleRequest(await datrix(), request)
  await sendWebResponse(res, response)
})

The same toWebRequest / sendWebResponse pair works for Fastify, Koa, and raw http.createServer — anything that exposes a Node.js-style request and response.

Features