Operations
Operations
All CRUD operations default to enabled β omitting the operations object, or a specific key, still exposes that endpoint. Set a key to false to disable it.
| Operation | HTTP Method | Route | Description |
|---|---|---|---|
findAll | GET | / | List all records (paginated) |
findOne | GET | /:id | Get one record by id |
create | POST | / | Create a new record |
update | PUT | /:id | Full replace β all fields required per schema |
patch | PATCH | /:id | Partial update β fields optional (auto .partial()) |
delete | DELETE | /:id | Delete a record |
Each key accepts three forms:
| Value | Meaning |
|---|---|
true (default) | Crouton registers and serves the endpoint |
false | Endpoint disabled β not registered |
{ "uri": "/path/{id}" } | External β client calls the given route directly; crouton registers nothing |
findAll and findOne additionally accept an object form to configure search, filter, and includes:
| Value | Meaning |
|---|---|
{ "search": ["field1", "field2"] } | Enable findAll with explicit free-text search fields |
{ "filter": ["field1"] } | Enable findAll with explicit filter fields (overrides per-column filterable) |
{ "search": [...], "filter": [...] } | Both |
{ "include": [...] } | Eagerly load relations for this operation (see Includes) |
When findOne.include is absent, crouton falls back to findAll.include.
Free-text search
The ?q= query parameter drives free-text search across the findAll endpoint.
Explicit search fields
Declare which fields to search via operations.findAll.search:
{
"operations": {
"findAll": { "search": ["title", "author"] }
}
}Relation fields resolve through their display key automatically β "author" becomes a contains on author.name if author.displayKey is "name".
Default: all fields
When findAll: true (no explicit search), crouton searches all non-id, non-relation, non-date columns automatically. To restrict search to specific fields, declare them explicitly.
{
"operations": { "findAll": true }
}{
"operations": {
"findAll": { "search": ["name", "email"] }
}
}The second form restricts search to name and email only.
Filters
operations.findAll.filter lists the columns that get a filter control in the table toolbar. It is also the server allowlist: a ?filter= on any other column (except the id field) is rejected with 400. Omit it to show no filter controls and accept filters on every column. Only the client's filters are checked: filters a beforeFindAll hook adds are trusted.
A dotted entry is a Prisma relation path, e.g. "tags.some.name" β ?filter=tags.some.name:x:equals becomes { tags: { some: { name: { equals: 'x' } } } }. It is allowed through the server allowlist but gets no toolbar control.
Filter values are converted to the field's type: on a boolean field only true / false are accepted, on a number field only numbers; anything else is rejected with 400. On these fields contains (the default operator) means equals and not_contains means not_equals.
{
"operations": {
"findAll": { "search": ["title"], "filter": ["status", "author"] }
}
}Migration from searchFields / filterFields
layout.table.searchFields / filterFields fail validation; per-column searchable / filterable flags are deprecated. Use migrate-to-next-alpha.md with an AI assistant to migrate automatically.
PUT vs PATCH
Both update and patch default to true. They share the same Prisma update() call β the difference is in validation:
update(PUT) uses the full update schema. All required fields must be present.patch(PATCH) usesupdateSchema.partial()by default (all fields optional).
In the frontend, manual save sends a PUT (full replace) and autosave sends a PATCH (partial update).
Hooks receive op: 'update' for PUT calls and op: 'patch' for PATCH calls, so beforeWrite/afterWrite hooks can distinguish between the two.
Per-operation security
Override the module-level security guard for a specific operation:
{
"operations": {
"findAll": true,
"delete": { "security": "admin" }
}
}The "admin" key refers to a named guard registered in CroutonApiModule. See Security for the full guard configuration.
External operations
Declare an operation as { "uri": "..." } to have the frontend call an external service directly for that operation, with crouton registering nothing internally:
{
"operations": {
"findAll": true,
"findOne": true,
"create": false,
"update": false,
"patch": false,
"delete": { "uri": "/annotation/{id}" }
}
}Crouton registers no NestJS route, no repository call, and no Prisma query for that operation. The compiled operations map the frontend consumes gets the external route as the uri β the client calls the external service directly.
How it works
The frontend's operations map is a set of { uri, method } entries per operation. Normally crouton fills in its own route (${baseUri}/{id} for delete, etc.). With an external op, the uri you declare is used directly, and the client calls it the same way it calls any other operation.
{id} and other {param} placeholders work exactly as they do with crouton routes β the client replaces them at call time.
Environment-variable placeholders
Use {env.VAR_NAME} in the route to reference an environment variable resolved at compile time:
{
"delete": { "uri": "{env.LEGACY_API}/annotation/{id}" }
}If LEGACY_API=https://legacy.example.com, the compiled uri becomes https://legacy.example.com/annotation/{id}. If the variable is unset, the placeholder is left intact.
Method override
The default HTTP method for each operation (get, post, put, patch, delete) is kept unless you override it:
{
"delete": { "uri": "/annotation/{id}", "method": "post" }
}Relative vs absolute routes
Relative routes are recommended for the first cut. A path like /annotation/{id} resolves against the axios baseURL (crouton's own API). Behind a reverse proxy this is the simplest setup and avoids cross-origin auth issues.
Absolute routes (https://legacy.example.com/...) work, but your frontend's axios interceptor will attach the user's bearer token to that foreign origin. If the external service should not receive it, configure axios to strip auth headers for non-same-origin requests, or use a server-side proxy in front of the external service.
Fully-external resources
A resource where every enabled operation has a uri needs no model, repository.ts, or custom adapter. It is naturally a kind: "custom" resource β columns still describe how the data is displayed, and crouton never touches the data itself.
{
"name": "legacy-annotation",
"route": "legacy-annotation",
"kind": "custom",
"operations": {
"findAll": false,
"findOne": false,
"create": { "uri": "/annotation" },
"update": { "uri": "/annotation/{id}" },
"delete": { "uri": "/annotation/{id}" }
},
"columns": {
"id": { "idField": true, "type": "string" },
"text": { "type": "string" }
}
}Read operations and response shape
delete, create, update, and patch are the safe choices for external ops β they have no response-shape contract with the crouton frontend.
findAll and findOne are supported but the external service must return crouton's envelope:
findAllβ{ data: [...], request: { count, page, pageSize, totalPages, ... } }findOneβ a row object matching the resource's columns
Restrict external ops to write operations for an initial integration, and add findAll/findOne only if you control the external service or add a translation layer.
When findAll is external, the lookup query endpoint (?q=) is also suppressed β crouton does not know how to proxy a text search to an arbitrary external service.