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)