macro_rules! api {
(
operations: [$($op:tt)+],
resource: $resource:ident,
name: $name:literal,
path: $base:literal,
state: $state:ident
$(,)?
) => { ... };
}http and validation only.Expand description
Generate JSON:API routes for one resource.
Pick the operations you want; nothing else is exposed. Routing every action a resource declares just because it exists is how internal operations leak, so this is opt-in.
ash_jsonapi::api! {
operations: [ash_jsonapi::CREATE, ash_jsonapi::READ],
resource: Todo,
name: "todo",
path: "/api/v1/todos",
state: App,
}| Operation | Route |
|---|---|
LIST | GET /todos |
CREATE | POST /todos |
READ | GET /todos/{id} |
UPDATE | PATCH /todos/{id} |
DELETE | DELETE /todos/{id} |
CRUD | all five |
STREAM | GET /todos, when Accept: application/jsonl |
INGEST | POST /todos, when Content-Type: application/jsonl |
CONTENT | GET /todos/{id}/content |
STREAM and INGEST share a verb with LIST and CREATE rather than
adding a route: one URL with two representations, selected by the header.
Routing either alongside its document counterpart is the usual case and
changes nothing for an existing client. Routing INGEST without
CREATE makes the collection batch-only, and a document body there is a
415.
The names are macro keywords, not items, so they work bare (READ) or
qualified (ash_jsonapi::READ) — write whichever reads better at the call
site. An unrecognised name is a compile error naming the valid ones.
Anything not listed is not routed: a [READ] resource answers 405 to a
DELETE, rather than reaching a handler that then refuses.
Fields:
operations— which routes to expose. Required: an empty list is a resource with no HTTP surface, which is a mistake worth spelling out.resource— your resource type.name— its JSON:APItype, for validator lookup.path— where it is mounted.state— your state type, implementingValidatorsand the traits for each operation you list.
Expands to pub fn routes() -> axum::Router<App> plus the handlers, in a
private module. Write your own route for anything the generated set does
not cover; this is a starting point, not a ceiling.