rest-api-design — SKILL.md

Variant: standard · When to use: the skill is invoked, applies the design decisions below to a resource surface, and returns a coherent contract; control passes back to the caller.

Overview

This skill is the design discipline for a REST/HTTP API and its contract — the layer above any web framework. It carries the opinionated defaults a senior engineer applies when turning a set of domain nouns into a consistent, evolvable HTTP surface: how to name resources, which method and status code each operation gets, one machine-readable error shape (RFC 9457 problem+json), a structured success and pagination envelope, a versioning stance, where auth and rate limiting live, and how the whole thing renders as an OpenAPI 3.1 contract. Code shown is Python/FastAPI + Pydantic v2 flavored, but every decision is language-agnostic. Framework mechanics (routers, dependency injection, response_model) and schema modeling belong to the fastapi and pydantic-v2 skills — this skill references them and does not duplicate them.

When to activate

• ✅ Designing a new API surface from a set of domain entities — what the endpoints, methods, and contract should be.
• ✅ Choosing the correct status code for an outcome, or deciding 400 vs 422, 401 vs 403, PUT vs PATCH.
• ✅ Defining or fixing the error model, the success envelope, or the pagination scheme of an API.
• ✅ Deciding a versioning, auth, or rate-limiting stance for an API.
• ✅ Turning an agreed REST design into an OpenAPI 3.1 contract.

Do NOT activate when: