Includes (?with=)
Ask an endpoint for extra, computed data with ?with=. A base response stays small and stable; sidecars add stats, access, and other derived data only when you request them.
A Chronicler read endpoint returns a stable base: enough of a resource for any consumer, and no more. It never fattens itself to fit one screen. When you need extra, derived data, you ask for it with the ?with= query parameter, and the endpoint attaches it as a sidecar.
GET /api/v1/chronicles/{id}/resources/{resourceId}?with=stats,access
Why sidecars, not a fat response
A sidecar is computed at query time and never stored, so it cannot go stale. Keeping it off the base has two payoffs. The base response stays small and fast for the callers that do not need the extra. And a sidecar that is expensive to compute is only paid for when a caller actually asks for it.
Ask for several at once by comma-separating them. An unknown name is ignored rather than erroring, so adding a ?with= value never breaks an older client.
Common sidecars
| Name | Adds |
|---|---|
stats | Computed counts about the entity, such as how many resources a chronicle holds. |
access | The calling principal's own capabilities on the entity, so a UI can show or hide actions. |
The exact set of sidecars a given endpoint supports is listed with that endpoint in the API reference.
A sidecar is additive
A sidecar never changes the base fields. It arrives as its own section of the response, alongside the base, so parsing the base does not depend on which sidecars you asked for.
{
"id": "chron_6311hvq3sgvd7vsmyxtmsh0sas",
"name": "The Black Company",
"stats": {
"resourceCount": 214,
"relationshipCount": 512
},
"access": {
"canWrite": true,
"canManageRoles": false
}
}
Resolved in one pass
A sidecar on a list resolves in a single batched pass, not a query per row. Asking for ?with=stats on a page of fifty resources costs one extra resolution, not fifty, so it stays cheap to request on a list.
Where to go next
- Every response also carries
createdAt,updatedAt, and, for chronicle-scoped entities,chronicleIdon the base. - See the design in Platform, API & deployment.