Related topics
- API Design & Integration — See practical API engineering patterns.
- Web with Axum — See Axum as a high-performance web framework.
- LLM Application Patterns — See API patterns from an LLM application perspective.
- Data Loading — See API design from the frontend data loading perspective.
- Web with net/http — See API design implemented in Go with net/http.
- GraphQL in Production — See GraphQL production patterns in depth.
- Data Fetching — See API design from the Vue/Nuxt data fetching perspective.
- Phoenix — See API design implemented with Phoenix.
API Design
APIs are the contracts between services, teams, and systems. In a distributed architecture, well-designed APIs determine how cleanly components can be developed independently, how easily new clients can integrate, and how gracefully a system can evolve over time. Poor API design creates tight coupling, versioning nightmares, and integration friction that compounds as a system grows.
Good API design goes far beyond choosing URL paths and HTTP methods. It involves selecting the right communication paradigm for each use case, defining clear resource models, handling errors consistently, managing authentication, and planning for how the API will change without breaking existing consumers. These decisions have long-lasting consequences because APIs, once published, are difficult to change.
This topic covers the major API paradigms used in modern systems: REST for resource-oriented services, gRPC for high-performance inter-service communication, and GraphQL for flexible client-driven queries. It also addresses the practical challenge of evolving APIs over time through versioning and backward-compatible changes.
What You'll Learn
- REST API Design - Principles for designing resource-oriented APIs using HTTP, including URL structure, status codes, pagination, filtering, and idempotency
- gRPC & Protocol Buffers - A high-performance RPC framework using binary serialization, covering when to choose gRPC over REST and how to define service contracts with protobuf
- GraphQL - A query language for APIs that lets clients request exactly the data they need, including its strengths, limitations, and when it is the right choice
- API Versioning & Evolution - Strategies for changing APIs without breaking existing clients, including URL versioning, header-based versioning, and backward-compatible schema changes
Prerequisites
A solid understanding of 01-fundamentals (especially networking fundamentals and HTTP) and familiarity with building or consuming web APIs. Exposure to 04-data-systems (data modeling in particular) helps when designing resource representations.