API Design Patterns

REST, GraphQL, and gRPC are the three dominant API styles, each optimised for a different context. REST is the standard for public APIs and browser clients — stateless, cacheable, and universally understood. GraphQL solves over-fetching for complex UIs — clients declare exactly the fields they need. gRPC uses Protocol Buffers over HTTP/2 for high-performance service-to-service calls — binary encoding is smaller and faster than JSON, with first-class streaming support. API versioning prevents breaking changes from reaching existing clients. URL versioning (`/v1/`, `/v2/`) is explicit and easy to route. Deprecation requires a sunset period — announce the timeline, log usage of old endpoints, and monitor adoption before removal.

// Client needs: name, avatar, follower_count
// REST returns the entire user object — 40 fields
GET /api/users/123
→ { id, name, email, bio, location, website,
    avatar, follower_count, following_count,
    created_at, updated_at, preferences, ... }

query {
  user(id: "123") {
    name
    avatar
    followerCount
  }
}
// Response: exactly 3 fields — nothing wasted
→ { name: "Alice", avatar: "...", followerCount: 1204 }