backend-api-contract

backend-api-contract

The contract is the test; the implementation is green when a generated client can exercise every endpoint.

What you do

Produce a precise, implementable contract for one service or one resource boundary — nothing more. The spec names every route, request shape, response shape, error envelope, auth expectation, and the versioning/pagination rules. A backend engineer should be able to start coding from it without asking a follow-up.

• Use nouns in URLs; verbs are the HTTP method. POST /orders, not POST /createOrder.
• Define the error envelope once (e.g. { error: { code, message, details } }) and reuse it.
• State auth per endpoint (public / bearer / service-token) and the required scope/role.
• Pick a versioning strategy (URL /v1/, header Accept: application/vnd.x.v1+json, or GraphQL schema evolution) and apply it consistently.
• Specify pagination shape (cursor + limit preferred for lists), sorting, and filtering grammar.
• Call out idempotency: which endpoints are safe to retry and which need an Idempotency-Key.

Output shape

Either an OpenAPI YAML fragment, a GraphQL SDL block, or a markdown spec with these sections:

1. Scope — resource(s) in scope; explicitly what's out.
2. Endpoints — method · path · summary · auth · request · response · errors.
3. Schemas — typed models for every request/response body.
4. Errors — error envelope + code table.
5. Auth & versioning — how clients authenticate, how versions evolve.
6. Pagination & idempotency rules.

Store at .guild/runs/<run-id>/api/<slug>.{yaml|md} if the run is tracked.

Anti-patterns

• Verbs in URLs (/createOrder, /getUser) — use HTTP methods.
• Missing error schema — errors are part of the contract, not an afterthought.
• Implicit auth — "obviously logged in" is not a spec.
• Breaking changes without versioning — renaming a field in v1 is a regression.
• Unbounded list endpoints — every list must cap limit and require pagination past it.
• String-typed everything — if a field is an enum, declare the enum.

Handoff

Return the spec path (or inline fragment) to the invoking backend specialist. If the contract implies DB work, the backend agent chains into backend-data-layer and backend-migration-writer; if it calls out to an external service, into backend-service-integration. This skill does not dispatch.