CRUD Collections

A crud collection connects a database model to a set of HTTP routes. You describe the fields of the model and list the routes you want, and StarkForge supplies the code behind each route: the eight database handlers and the three file handlers. Nothing is exposed automatically. A collection without routes has no endpoints, so the route list is your whole API for that model.

At start-up StarkForge registers the model with the data source, marks its secret fields and creates its indexes. The keys of a collection are described in Collections, and this page shows how to choose routes for it.

The Endpoints of a Collection

The products collection on the Collections page lists eight routes. With the default prefix, they create these endpoints:

The URL is the prefix /api/v1, the route of the collection and the path of the route. The paths in this table are the convention of this documentation. Routes explains how to choose your own, why a parameter must be named id and which rules StarkForge checks when the server starts.

Choosing Routes

Start from who uses the data, then list only the routes that group needs. Three patterns cover most collections.

A Public Catalog

Visitors read the data and staff change it, as in the products collection above. List readAll and read with auth: "public", the write handlers with auth: "authenticated" and a list of roles, and the delete handlers with auth: "admin". A public route needs no sign-in at all, so keep it to reads.

Private Data for Each User

Each person sees only their own documents, and administrators see all of them. Add an owner field to the schema with fields.userRef. The create handler fills it from the session, and admin-or-owner then limits the other handlers to the owner and to administrators. On readAll, the list contains only the documents of the caller.

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

export const notes = collection({
  type: "crud",
  route: "notes",
  model: "Note",
  schema: {
    title: fields.requiredString,
    body: fields.optionalString,
    owner: fields.userRef,
  },
  validations: {
    create: { title: z.string().min(1), body: z.string().optional() },
    update: { title: z.string().min(1).optional(), body: z.string().optional() },
  },
  routes: defineRoutes([
    { method: "get", path: "/", handler: "readAll", auth: "admin-or-owner" },
    { method: "get", path: "/:id", handler: "read", auth: "admin-or-owner" },
    { method: "post", path: "/", handler: "create", auth: "authenticated", validation: "create" },
    { method: "patch", path: "/update/:id", handler: "update", auth: "admin-or-owner", validation: "update" },
    { method: "delete", path: "/delete/:id", handler: "remove", auth: "admin-or-owner" },
  ]),
});

The field must be named owner, and it is left out of the validation groups, so a client cannot choose the owner of a document. Authorization explains ownership in full.

An Admin-Only Back Office

Give every route auth: "admin". Who counts as an administrator is the adminRoles option, which holds admin by default.

One Page per Handler

Each handler has a page that shows its request, its response and its errors:

• Create saves one document and answers 201.
• Bulk Create saves a JSON array of documents in one request.
• Read returns one document by id.
• Read All lists documents, 50 to a page by default and at most 100, newest first.
• Update changes the fields that the body contains.
• Delete removes one document, a list of documents or every document.
• Uploads covers the three file handlers: addFile, updateFile and deleteFile.
• Relations and Hidden and Encrypted Fields change what comes back in a response.

Where to Go Next

:::