API Design and Versioning

Design APIs people can rely on: resources, HTTP semantics, errors, pagination, idempotency, security, versioning, deprecation and governance, tested with a real running API.

Start course →

Syllabus

Principles of Good API Design

  1. What Makes an API Good
  2. Resources and URLs
  3. HTTP Methods and Their Guarantees
  4. REST, GraphQL, gRPC and Webhooks: Choosing a Style

Requests, Responses and Errors

  1. Choosing Status Codes
  2. Error Responses: Problem Details
  3. Pagination: Offset vs Cursor
  4. Filtering, Sorting and Field Selection

Reliability and Performance

  1. Idempotency Keys
  2. Caching and Conditional Requests (ETag)
  3. Rate Limiting and Quotas
  4. Long-Running Operations and Bulk Requests

Security and Trust

  1. Authentication and Authorisation
  2. Object-Level Authorisation and Data Exposure
  3. Webhooks: Signing and Verifying

Versioning and Evolution

  1. What Counts as a Breaking Change
  2. Versioning Strategies
  3. Content Negotiation and the Accept Header
  4. Running v1 and v2 Side by Side

Deprecation and Migration

  1. Deprecation and Sunset Headers
  2. Timelines, Communication and Usage Tracking
  3. Compatibility Layers and Gradual Migration

Contracts, Testing and Governance

  1. Contract-First with OpenAPI
  2. Testing the API and the Contract
  3. Documentation, SDKs and API Governance

Putting It Together

  1. Case Study: A Payments and Items API
  2. Revision: Cheat Sheet and Self-Check