Routes

A route is one endpoint of a collection: an HTTP method, a path, a handler that does the work and the settings that say who may call it and what it may do. This page lists every field of a route, the rules that StarkForge enforces when the server starts and the two mistakes that cause confusing symptoms.

A Route List With Notes

Routes live in the routes list of a collection. This list gives anyone read access, lets editors and administrators write, and keeps deletion for administrators:

// src/collections/products.ts
import { collection, defineRoutes, fields } from "@starklabs/forge";
import { z } from "zod";

export const products = collection({
  type: "crud",
  route: "products",
  model: "Product",
  schema: {
    name: fields.requiredString,
    price: fields.requiredNumber,
  },
  validations: {
    create: { name: z.string().min(1).max(120), price: z.number().min(0) },
    update: { name: z.string().min(1).max(120).optional(), price: z.number().min(0).optional() },
  },
  routes: defineRoutes([
    // Anyone may list and read products.
    { method: "get", path: "/", handler: "readAll", auth: "public" },
    { method: "get", path: "/:id", handler: "read", auth: "public" },
    // Signed-in editors and administrators may create and change products.
    { method: "post", path: "/", handler: "create", auth: "authenticated", roles: ["editor", "admin"], validation: "create" },
    { method: "patch", path: "/update/:id", handler: "update", auth: "authenticated", roles: ["editor", "admin"], validation: "update" },
    // Only administrators may delete.
    { method: "delete", path: "/delete/:id", handler: "remove", auth: "admin" },
  ]),
});

Route Fields

The access levels are "public", "authenticated", "admin" and "admin-or-owner". An access level is not a role: roles lists values such as editor, and the Authorization page explains how the two combine.

Default Access Levels

A route without auth gets the default of its collection type:

A CRUD route that you leave without auth therefore needs a signed-in user. If you configured no sign-in at all, those routes answer 401 to everyone, and StarkForge logs a warning when it starts.

Paths

A path is any string that Express accepts, and it is added to the collection's route. These shapes are the convention that this documentation follows, but none of them is required:

Two rules matter. The parameter of a handler that works on one document must be named id, because the handlers read req.params.id, and its value must be a MongoDB id of exactly 24 hexadecimal characters. Any other value is answered with status 400 and the code INVALID_OBJECT_ID.

Express checks routes in the order you list them, so put specific paths before parameterized ones. With /:id first, a request for /products/latest matches /:id and fails:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "success": false,
  "message": "The id in the URL is not valid.",
  "code": "INVALID_OBJECT_ID",
  "requestId": "0add8d45-8e76-4f44-8342-32dda7eab138"
}

List { method: "get", path: "/latest", handler: "readAll", auth: "public" } before the /:id entry and the same request reaches its own route.

Rules Checked at Start-up

StarkForge checks every route when the server starts, and reports all problems of a collection at once, as Collections shows. These are the rules:

The messages quote the method and path of the route, so you can find it. This one comes from a roles entry on a public route:

 - GET /things/mine: 'roles' cannot be used on a 'public' route: nobody is signed in, so nobody has a role. Use auth: 'authenticated'.

A Route Without Validation Accepts No Body

A route that reads a body must name a validation group. Without validation, StarkForge discards every body field, so the handler works on an empty body. Two symptoms follow.

A create route without validation saves an empty document. When the schema requires a field, the client sees an error about a field it did send:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "success": false,
  "message": "name: Path `name` is required.",
  "code": "VALIDATION_FAILED",
  "issues": [
    {
      "path": "name",
      "message": "Path `name` is required.",
      "code": "required"
    }
  ],
  "requestId": "0add8d45-8e76-4f44-8342-32dda7eab138"
}

An update route without validation is quieter: it answers 200, returns the document, and changes nothing, because the fields you sent were discarded. When a write seems to be ignored, check the validation key first.

Where to Go Next

:::