API Design

Overview

Design REST and HTTP APIs that are consistent, predictable, and generate clean client code through OpenAPI tooling. Good APIs are obvious to consume, hard to misuse, and survive multiple generations of clients.

When to Use

• Designing new API endpoints or an entire API surface
• Writing or reviewing OpenAPI / Swagger specifications
• Naming resources, choosing HTTP methods, or structuring URLs
• Designing pagination, filtering, sorting, or search
• Choosing error response formats
• Planning API versioning strategy
• Reviewing an existing API for consistency and ergonomics

Instructions

Step 1: Clarify the API Context