Design API contracts, schemas, and specifications before implementation.
Process
- Identify context:
- Protocol: REST, GraphQL, gRPC, TRPC - Format: OpenAPI/Swagger, Protocol Buffers, Zod/TypeBox schemas
- Research and design:
- Lookup best practices for the protocol (use WebSearch/WebFetch) - Design the API resources, endpoints, and data shapes - Consider versioning, pagination, error handling patterns
- Output the design:
- Endpoints/Operations: Method, Path, Name - Request Schema: input validation rules - Response Schema: Success/Error shapes - Examples: JSON/Text payloads
Output
- API Specification (OpenAPI YAML, Proto file, or Interface code)
- Usage Example (curl or client code)
- Design Rationale (RESTfulness, Breaking changes avoidance)