z-go-api-design
Installation
SKILL.md
REST API contract design
The contract is what's frozen into openapi.yaml before ogen generates a single line of transport code. Get these decisions right there — regenerating code is cheap, migrating clients off a wrong contract is not.
Quick reference
| Decision | Default | Escalate to |
|---|---|---|
| Versioning | Path (/v1) |
— pick once, org-wide |
| Pagination | Keyset/cursor | Offset only for small bounded admin lists |
| Idempotency | Idempotency-Key + server-side key store |
required on every unsafe POST that creates or charges |
| Errors | RFC 9457 application/problem+json |
— one shared schema, always |
| Update semantics | PATCH = JSON Merge Patch (RFC 7396) |
JSON Patch (RFC 6902) only for array-position ops or atomic test preconditions |
| Concurrency | none (last-write-wins) | ETag/If-Match once lost updates are a real, reported problem |