| name | bondery-api |
| description | Bondery Fastify API contracts — transport wrappers, list pagination (offset/search/sort), resource-keyed responses, mutations, Stripe-style errors, route registration order, mobile sync, rate limits, and versioning. Use when adding or changing API routes, client API calls, OpenAPI, sync protocol, or API error codes.
|
| metadata | {"version":"1.0.0","namespace":"bondery"} |
Bondery API
When to use
- Adding or changing Fastify routes, Zod schemas, or OpenAPI docs
- Implementing client HTTP calls (webapp BFF, mobile, chrome extension)
- Designing list endpoints, pagination, search, or sort behavior
- Create/update mutation responses or error codes
- Mobile offline sync (pull, outbox, materializers)
- Rate limiting or API versioning questions
Non-negotiables
- Clients call the API through transport wrappers — never scattered raw
fetch with duplicated auth
- Success responses are resource-keyed (
{ contact }, { contacts, pagination }) — not { data }
- Errors use
{ error: { code, type, message, doc_url, ... } } — catalog codes only, snake_case
- Paginated lists use offset pagination (
limit, offset) — no cursor / page_token / after_id
- Query param is
search, not q
- Create returns
201 + full resource object — see references/api-mutations.md
- Fastify routes use Zod +
fastify-zod-openapi — not TypeBox
- Registration order is published doc order — see
references/api-route-ordering.md
Decision tree
Full index: references/README.md.
For client error display and i18n, see the bondery-ux skill (references/common/api-errors-display.md). For E2E coverage of API-facing flows, see bondery-e2e-tests. For auth, tenant isolation, webhooks, uploads, and route security, see bondery-security.
API design checklist (before merge)
