API Design

Principles and patterns for designing APIs that are consistent, predictable, and easy to evolve. Applies to any language or framework — the focus is on protocol-level design decisions, not implementation details.

A well-designed API treats its surface as a product: consumers should be able to predict behavior, recover from errors, and integrate without reading source code.

When to Use

• Designing a new public or internal API from scratch
• Reviewing an existing API for consistency and usability
• Choosing between REST and GraphQL for a project
• Planning API versioning or migration strategy
• Defining error response contracts across services
• Establishing API standards for a team or organization

REST vs GraphQL