Built-In Operations

CRUD Operations

These six operations are auto-generated for every model registered with add() or prepare().

GetList

GET /resources

Fetches all items from the collection, filtered and sorted by middleware.

Aspect	Detail
Status code	200
Middleware hook	@getList
Response	Serialized list wrapped in plural key

The operation streams results via InputRange!Json to avoid loading entire collections into memory. Middleware can filter, sort, limit, and skip results through the IQuery interface.

GetItem

GET /resources/:id

Fetches a single item by ID.

Aspect	Detail
Status code	200 (or 304 if ETag matches)
Middleware hook	@getItem
Response	Serialized item wrapped in singular key

Generates an ETag from the item’s hash field (if present) or CRC32 of the JSON. If the client sends If-None-Match matching the ETag, returns 304 Not Modified with an empty body.

CreateItem

POST /resources

Creates a new item.

Aspect	Detail
Status code	201 Created
Middleware hook	@create
Response	Serialized created item
Location header	Set to the new item’s URL

The flow:

1. Deserialize request body via the protocol’s serializer
2. Check for ID conflicts (409 Conflict if ID already exists)
3. Wrap in Lazy!T to resolve relation references (IDs → full objects)
4. Materialize to concrete type, then back to storage JSON
5. Insert via crate.addItem()
6. Set Location header to the new resource URL

UpdateItem (PATCH)

PATCH /resources/:id

Partially updates an item. Client sends only the fields to change.

Aspect	Detail
Status code	200
Middleware hook	@patch, @update
Response	Serialized updated item (full)

The operation merges client data with existing stored data — client fields overwrite, unmentioned fields are preserved. Relation fields are validated to contain IDs, not nested objects.

ReplaceItem (PUT)

PUT /resources/:id

Completely replaces an item. Client sends the full object.

Aspect	Detail
Status code	200
Middleware hook	@put, @replace
Response	Serialized replaced item

Unlike PATCH, PUT does not merge. The entire item is replaced with the client’s data.

DeleteItem

DELETE /resources/:id

Removes an item.

Aspect	Detail
Status code	204 No Content
Middleware hook	@delete_
Response	Empty body

If the model has resource fields (files, images), they are cleaned up before deletion.

---

Action Operations

ItemMethodApiOperation

POST /resources/:id/:methodName

Executes a custom method defined on the model struct. Auto-discovered when the struct has methods annotated with @Action:

struct Article {
  string _id;
  string title;
  bool published;

  @Action
  void publish() {
    published = true;
  }
}

The operation fetches the item, converts it to the native type, calls the method, and stores the updated item.

ItemApiOperation

POST /resources/:id/:action

A more flexible variant. Instead of calling a method on the model, it delegates to a custom callable that receives the full OperationContext:

crateRouter.prepare(articleCrate)
  .itemOperation!("export", new ExportOperation);

---

Resource Operations

For models with binary resource fields (images, files, audio):

GetResource

GET /resources/:id/fieldName

Streams a binary resource field. Sets Content-Type, ETag, Cache-Control: public, and Content-Length headers. Supports 304 Not Modified via If-None-Match.

SetResource

POST /resources/:id/fieldName

Uploads a binary resource to a field on an item. Reads the file from the request body and updates the item.

---

JSON:API Relationship Operations

These are generated only by the JsonApi policy, following the JSON:API specification for relationship endpoints.

RelationshipGet

GET /resources/:id/relationships/:relationship

Returns relationship data as resource identifier objects:

To-One

{
  "jsonapi": {"version": "1.1"},
  "data": {"type": "team", "id": "abc123"}
}

To-Many

{
  "jsonapi": {"version": "1.1"},
  "data": [
    {"type": "tag", "id": "tag1"},
    {"type": "tag", "id": "tag2"}
  ]
}

RelationshipPost

POST /resources/:id/relationships/:relationship

Appends items to a to-many relationship. Duplicates are skipped.

{
  "data": [
    {"type": "tag", "id": "newTag1"},
    {"type": "tag", "id": "newTag2"}
  ]
}

RelationshipPatch

PATCH /resources/:id/relationships/:relationship

Replaces the entire relationship. Send null to clear it.

Replace To-One

{"data": {"type": "author", "id": "newAuthorId"}}

Clear

{"data": null}

RelationshipDelete

DELETE /resources/:id/relationships/:relationship

Removes specific items from a to-many relationship. Non-existent IDs are silently ignored.

{
  "data": [
    {"type": "tag", "id": "tagToRemove"}
  ]
}

---

Shared Behavior

Middleware Execution

All operations execute middleware in two phases:

1. Non-query middleware — request validation, authentication, header setting
2. Query middleware — filters, sorting, pagination via IQuery

If any middleware writes a response (e.g., 401 Unauthorized), the operation stops.

ETag Caching

Item operations (GET, PUT, PATCH) generate ETags:

1. If the item has a hash field, use it directly
2. Otherwise, compute CRC32 of the JSON string

Clients can send If-None-Match to receive 304 responses.

Path Variable Extraction

All item operations extract the :id from the URL path using the rule’s path template. The ID is stored in OperationContext for middleware and the operation to use.

Response Serialization

Operations use the protocol’s serializer to format responses:

• toResponseItem() for single items
• toResponseList() for collections

Response mappers (@mapper) run before serialization, transforming each item to add computed properties or hide fields.

---

MCP-Specific Operations

These operations are registered automatically when using the MCP policy. They are not CRUD operations — they provide protocol-level functionality for AI clients.

get_upload_instructions

Discovers REST upload endpoints for file resource fields. Given a model, resource ID, and field name, returns the URL, HTTP method, and content type needed to upload a file directly via REST instead of base64-encoding it through MCP tool arguments.

Aspect	Detail
Tool name	get_upload_instructions
Parameters	model (required), id (required), field (required)
Response	Upload URL, method, content type, and example curl command
Fallback	Suggests the base64 set_*_value tool if no REST endpoint exists

get_list_query_options

Returns the available query/filter parameters for a model’s list endpoint as a JSON Schema object. AI clients use this to discover filtering, pagination, and search options before calling list_* tools.

Aspect	Detail
Tool name	get_list_query_options
Parameters	model (required)
Response	JSON Schema describing available query parameters

The tool description in tools/list is automatically updated with the list of available models.

Notification

Handles MCP lifecycle notifications (notifications/initialized) and ping requests.

Aspect	Detail
Method	notifications/initialized or ping
Notifications response	202 Accepted (empty body)
Ping response	JSON-RPC success with empty result object

---

IQuery Interface

The IQuery interface is used by query middleware to build database queries. It exposes:

Method	Return	Description
where(field)	IQuery	Add a field filter
limit(n)	IQuery	Limit result count
skip(n)	IQuery	Skip first N results
size()	size_t	Exact count of matching items (respects filters)
estimatedSize()	size_t	Estimated collection size from metadata (no filter, no collection scan)

estimatedSize() is significantly faster than size() because it reads collection metadata rather than scanning documents. It does not account for applied filters — use it when you need a rough magnitude estimate (e.g. for AI clients to understand data scale before querying).