rest-api

name	rest-api
description	Team conventions for designing and shipping REST APIs — resource modeling, the OpenAPI-first workflow, and contract testing. Use when designing or building HTTP endpoints. Use when this capability is needed.
metadata	{"author":"atlasfoo"}

rest-api

How this team designs and ships REST endpoints.

Design first

Before any endpoint is built, its shape is agreed: resource, HTTP verb, path, request/response schema, status codes, and error cases. A feature that adds endpoints must list them explicitly up front.

OpenAPI-first

• The source of truth is openapi.yaml at the service root.
• New or changed endpoints are written into openapi.yaml before implementation.
• Handlers are expected to match the spec; drift is a bug.

Contract testing

• Every endpoint has a contract test asserting the response matches the OpenAPI schema (status code, body shape, error envelope).
• Contract tests run in CI and block merge on drift.

Conventions

• Plural nouns for collections (/bookings), no verbs in paths.
• Cursor pagination for list endpoints.
• Errors use a consistent envelope: { "error": { "code", "message" } }.

---

Source: atlasfoo/jaiba-framework — distributed by TomeVault.