Api Design

API Design

Trigger phrases: "api design", "api contract", "api versioning", "openapi", "swagger", "rest contract", "breaking api change", "response shape", "response format", "endpoint returns", "error format"

Goal: a contract the consumer can predict and that can evolve without breaking. Once published, a public API is a commitment; a breaking change is expensive. Stack-agnostic (REST as the baseline; GraphQL/gRPC follow similar principles).

Checklist

• [ ] Resource names are consistent (plural nouns, a single kebab/camel style), resources not verbs
• [ ] Correct HTTP semantics: GET (side-effect free) · POST · PUT/PATCH · DELETE; correct status code
• [ ] A uniform error model: machine-readable code + human message + (if any) field details
• [ ] A clear versioning strategy (URL /v1 or header); a breaking change means a new version
• [ ] Pagination/filtering/sorting defined and consistent on large collections
• [ ] Backward compatibility: adding a field is additive; removing a field or changing its meaning is breaking → version
• [ ] Idempotency (for POST/payment-like cases) supported via a key when needed
• [ ] The contract is documented in OpenAPI; example request/response present (coordinate with docs-writer)

How

1. Model the resource — a noun not a verb: POST /orders (✓), POST /createOrder (✗).
2. Status codes: 200/201/204 · 400 validation · 401/403 authorization · 404 · 409 conflict · 422 · 429 · 5xx. Use them meaningfully.
3. Error contract — every error has the same shape:

``json { "code": "ORDER_NOT_FOUND", "message": "Order not found", "details": [] } ` No stack trace / internal detail leakage (overlaps with security-scan`).

1. Versioning: additive changes in the same version; breaking (remove/rename a field / add a required field) → /v2.
2. Collection: pagination (cursor or offset), filter/sort parameters; a consistent envelope.
3. Write the contract — OpenAPI/schema; with examples. Wire the change to docs-writer, and if breaking to release/CHANGELOG.

Breaking vs additive

| Additive (safe) | Breaking (needs a version) | |---|---| | Add an optional field/endpoint | Remove / rename a field | | A new optional parameter | Add a required parameter | | A new enum value (if the consumer is tolerant) | Change a type/meaning, change a status code |

Invariant rules

1. A public API is a commitment — a breaking change is not made silently; version + announcement.
2. Consistency > local cleverness — a single naming/error/pagination pattern across the whole API.
3. The error model is uniform and machine-readable.
4. No internal detail leakage — a stack trace / DB error does not go to the consumer.
5. The contract is documented — OpenAPI + example; at design time, not after the code.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: crewforth
• Source: crewforth/crewforth
• License: MIT
• Homepage: https://crewforth.com/

Install and usage instructions live in the source repository linked above.