API Design

A blog series

API Design: REST, GraphQL and gRPC From Zero

How to design an API other developers enjoy using: resources and URLs, methods and status codes, errors, pagination, versioning, idempotency, authentication, rate limits, OpenAPI, and when to choose GraphQL or gRPC. Small examples, every one run.

Started 
2026
Lessons 
10
Reading 
~2 h

Contents

Every lesson has the same steps: what it is, how it works, a real example, common mistakes, then interview questions with answers you can say out loud.

  1. Lesson 00What Makes a Good API: Resources, URLs and the ContractWhat an API contract is, REST in plain words, naming resources and URLs, and the rules that make an API predictable.12 min
  2. Lesson 01HTTP Methods, Status Codes and Idempotency in PracticeGET, POST, PUT, PATCH and DELETE used correctly, the status codes that matter, and why idempotency decides whether a retry is safe.14 min
  3. Lesson 02Request and Response Design: JSON Shapes, Errors and ValidationConsistent JSON, naming, dates and money, one error format (RFC 9457 problem details), validation with clear messages, and what never to return.14 min
  4. Lesson 03Pagination, Filtering and SortingOffset versus cursor pagination with real timings, stable ordering, filters, sorting, and how to return links and counts.14 min
  5. Lesson 04Versioning, Compatibility and Evolving an APIBreaking versus safe changes, URL, header and date versions, deprecation, and how to change an API without breaking clients.13 min
  6. Lesson 05Idempotency Keys, Retries, Webhooks and Rate LimitsSafe retries with idempotency keys, webhooks with signatures and retries, rate limit headers, and long-running jobs.15 min
  7. Lesson 06API Authentication and Authorization: API Keys, OAuth 2.0 and ScopesAPI keys, bearer tokens, OAuth 2.0 flows in plain words, scopes, and common mistakes. Ties back to the Security series.15 min
  8. Lesson 07Documenting APIs: OpenAPI, Contracts and TestingWrite an OpenAPI file, generate docs, validate requests and responses against it, contract tests and mock servers.13 min
  9. Lesson 08GraphQL and gRPC: When Not to Use RESTWhat problems GraphQL and gRPC solve, the real costs (N+1, caching, tooling), a small working example of each, and a decision table.15 min
  10. Lesson 09API Design Interview Questions and Review ChecklistA checklist to review any API, and the questions interviewers ask with model answers.15 min

Glossary

42 terms used in this series. Inside any lesson, hover or tap a dotted term to see its meaning without leaving the page. Browse all terms →