api-contract-design
Contract-first API development — error semantics, status codes, request/response design, OpenAPI/Swagger standards. Prevents inconsistent APIs and breaking changes without migration paths.
Файлы1
Открыть в GitHubSKILL.mdskills/api-contract-design/SKILL.md
GitHubAPI Contract Design
Problem it solves
APIs built without contracts develop inconsistencies and breaking changes:
- Inconsistent error formats (sometimes string, sometimes object, sometimes nothing)
- Missing status codes (everything returns 200 with errors in the body)
- Breaking changes without version bumps or migration paths
- Undocumented endpoints that only the author understands
- Inconsistent naming (sometimes camelCase, sometimes snake_case)
- No request validation — bad input causes 500s instead of 400s
Protocol
1. Contract-first design
Before writing any API implementation, define the contract:
- Operations: what endpoints exist and what do they do
- Requests: what input does each endpoint accept (path params, query params, body)
- Responses: what does each endpoint return (success and error shapes)
- Status codes: what HTTP status codes are used for each outcome
- Error format: a consistent error structure across all endpoints
2. HTTP status code conventions
| Code | When to use |
|---|---|
| 200 OK | Successful GET, PUT, PATCH |
| 201 Created | Successful POST (resource created) |
| 204 No Content | Successful DELETE |
| 400 Bad Request | Invalid input, missing required fields, validation failure |
| 401 Unauthorized | Missing or invalid authentication |
| 403 Forbidden | Authenticated but not authorized |
| 404 Not Found | Resource does not exist |
| 409 Conflict | Resource state conflict (duplicate, stale version) |
| 422 Unprocessable | Semantic validation failure (business rule violation) |
| 429 Too Many Requests | Rate limit exceeded |
| 500 Internal Server | Unexpected server error (do not expose details) |
3. Error response format
Every error response should follow a consistent structure:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "A human-readable description",
"details": [
{ "field": "email", "reason": "must be a valid email address" }
]
}
}
4. API versioning
- Use URL-based versioning (
/v1/,/v2/) or header-based (Accept header) - Never remove or modify existing fields in a version
- Adding a field is safe (consumers ignore unknown fields)
- Changing a field or removing one requires a new version
- Deprecate before removing: add
Deprecationheader, keep old version for N months
5. Request/Response design rules
- Use standard HTTP methods: GET (read), POST (create), PUT (replace), PATCH (partial update), DELETE (remove)
- Use standard content types:
application/jsonfor REST APIs - Pagination: Always paginate list endpoints. Return
{ data: [...], next: "url" }or{ data: [...], total, page, size } - Filtering/Sorting: Use query parameters (
?status=active&sort=name:asc) - Idempotency: PUT and DELETE should be idempotent. POST should return 201 with Location header
- Naming: Use plural nouns for resources (
/users, not/user). Use kebab-case for paths (/user-profiles)
6. OpenAPI/Swagger
- Document every endpoint with OpenAPI 3.x
- Include request/response schemas, examples, and error responses
- Keep the spec in version control alongside the code
- Generate client libraries and server stubs from the spec when possible
Detection triggers
Activate when:
- Designing or implementing an API endpoint
- Modifying an existing API contract
- Adding request/response handling
- User says "design API", "create endpoint", "build REST API"
- Reviewing API changes in a PR
When NOT to use
- Internal function/method signatures (use spec-driven-development)
- GraphQL APIs (schema-first with different conventions)
- RPC or event-driven architectures
- User explicitly says "no contract needed"
Cross-references
spec-driven-development — Write the API contract as part of the spec before implementation.
test-driven-development — Test the API contract (request/response shapes, status codes, error formats) before implementation.
code-review — The architecture axis should verify API contracts follow these conventions.
adr-and-documentation — API contract changes should be documented in ADRs. OpenAPI specs are living documentation.
security-best-practices — API security (auth, rate limiting, input validation) should be designed into the contract, not added later.
follow-existing-patterns — API contracts must match the project's existing API conventions (naming, versioning, error format).
git-workflow-conventional-commits — Breaking API changes should be clearly marked with BREAKING CHANGE footer.