Skip to main content

api

Macro api 

Source
macro_rules! api {
    (
        operations: [$($op:tt)+],
        resource: $resource:ident,
        name: $name:literal,
        path: $base:literal,
        state: $state:ident
        $(,)?
    ) => { ... };
}
Available on crate features 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,
}
OperationRoute
LISTGET /todos
CREATEPOST /todos
READGET /todos/{id}
UPDATEPATCH /todos/{id}
DELETEDELETE /todos/{id}
CRUDall five
STREAMGET /todos, when Accept: application/jsonl
INGESTPOST /todos, when Content-Type: application/jsonl
CONTENTGET /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:API type, for validator lookup.
  • path — where it is mounted.
  • state — your state type, implementing Validators and 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.