147 lines
4.6 KiB
Markdown
147 lines
4.6 KiB
Markdown
---
|
|
name: api-contract-design
|
|
description: "Knowledge contract for defining API contracts, request/response schemas, status codes, pagination, authentication boundaries, and idempotency behavior. Referenced by design-architecture when defining APIs."
|
|
---
|
|
|
|
This is a knowledge contract, not a workflow skill. It is referenced by `design-architecture` when the architect is defining API contracts.
|
|
|
|
## Core Principles
|
|
|
|
- APIs are contracts between producers and consumers; stability and clarity are paramount
|
|
- Every endpoint must serve at least one PRD functional requirement
|
|
- Contracts must be explicit, complete, and unambiguous
|
|
- Breaking changes must be avoided; versioning must be planned
|
|
|
|
## REST API Design
|
|
|
|
### Endpoint Definition
|
|
|
|
For each endpoint, define:
|
|
- HTTP method (GET, POST, PUT, PATCH, DELETE)
|
|
- Path (e.g., `/api/v1/jobs`)
|
|
- Description
|
|
- PRD functional requirement it satisfies
|
|
- Authentication requirements
|
|
- Idempotency behavior (when applicable)
|
|
|
|
### Request Schema
|
|
|
|
For each endpoint, define:
|
|
- Path parameters (name, type, description, validation rules)
|
|
- Query parameters (name, type, required/optional, default, validation rules)
|
|
- Request headers (name, required/optional, purpose)
|
|
- Request body (JSON schema with types, required fields, validation rules)
|
|
|
|
### Response Schema
|
|
|
|
For each endpoint, define:
|
|
- Success response (status code, body schema)
|
|
- Error responses (each status code, body schema, conditions that trigger it)
|
|
- Pagination metadata (when applicable)
|
|
|
|
### Status Codes
|
|
|
|
Use status codes semantically:
|
|
- `200 OK` - successful retrieval or update
|
|
- `201 Created` - successful resource creation
|
|
- `204 No Content` - successful deletion or action with no response body
|
|
- `400 Bad Request` - client sent invalid input
|
|
- `401 Unauthorized` - missing or invalid authentication
|
|
- `403 Forbidden` - authenticated but not authorized
|
|
- `404 Not Found` - resource does not exist
|
|
- `409 Conflict` - state conflict (duplicate, version mismatch)
|
|
- `422 Unprocessable Entity` - valid format but business rule violation
|
|
- `429 Too Many Requests` - rate limit exceeded
|
|
- `500 Internal Server Error` - unexpected server error
|
|
- `502 Bad Gateway` - upstream service failure
|
|
- `503 Service Unavailable` - temporary unavailability
|
|
- `504 Gateway Timeout` - upstream timeout
|
|
|
|
### Pagination Model
|
|
|
|
For list endpoints, define:
|
|
- Pagination strategy (cursor-based recommended, offset-based acceptable)
|
|
- Page size limits (default and maximum)
|
|
- Sort order (default and available fields)
|
|
- Total count availability (when to include, performance implications)
|
|
|
|
Cursor-based pagination is preferred for:
|
|
- Large datasets
|
|
- Real-time data that shifts during pagination
|
|
- Performance-sensitive endpoints
|
|
|
|
Offset-based pagination is acceptable for:
|
|
- Small, stable datasets
|
|
- When random access by page number is required
|
|
|
|
### Filtering & Sorting
|
|
|
|
For list endpoints, define:
|
|
- Available filter parameters and their types
|
|
- Filter combination rules (AND, OR, support for complex queries)
|
|
- Sort fields and sort direction
|
|
- Default sort order
|
|
|
|
### Authentication Boundary
|
|
|
|
Define:
|
|
- Which endpoints require authentication
|
|
- Authentication mechanism (API key, JWT, OAuth, etc.)
|
|
- Token scope requirements per endpoint
|
|
- Rate limiting per authentication tier (when applicable)
|
|
|
|
### Error Response Format
|
|
|
|
Define a consistent error response schema:
|
|
```json
|
|
{
|
|
"error": {
|
|
"code": "ERROR_CODE",
|
|
"message": "Human-readable message",
|
|
"details": [
|
|
{
|
|
"field": "field_name",
|
|
"code": "VALIDATION_ERROR",
|
|
"message": "Specific error message"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Versioning Strategy
|
|
|
|
- Prefer URL path versioning (e.g., `/api/v1/`) for public APIs
|
|
- Prefer header versioning for internal APIs when appropriate
|
|
- Define breaking vs non-breaking change policy
|
|
- Define deprecation timeline for old versions
|
|
|
|
## Non-REST APIs
|
|
|
|
### GraphQL
|
|
- Define schema (types, queries, mutations, subscriptions)
|
|
- Define resolver contracts
|
|
- Define pagination model (cursor-based connections)
|
|
- Define error handling in responses
|
|
|
|
### gRPC
|
|
- Define service definitions in proto files
|
|
- Define message types
|
|
- Define streaming patterns
|
|
- Define error status codes
|
|
|
|
### WebSocket
|
|
- Define message schema (message types, payload formats)
|
|
- Define connection lifecycle (connect, reconnect, disconnect)
|
|
- Define authentication for initial connection
|
|
- Define error handling within messages
|
|
|
|
## API Contract Anti-Patterns
|
|
|
|
- Endpoints without a PRD functional requirement
|
|
- Vague or inconsistent error response formats
|
|
- Missing pagination on list endpoints
|
|
- Authentication applied inconsistently
|
|
- Breaking changes without versioning
|
|
- Over-nested response structures
|
|
- Exposing internal implementation details through API shape |