API design reading path: build clean, durable REST and beyond
This curriculum takes an intermediate engineer from solid REST fundamentals through the nuanced craft of API contracts, versioning strategies, and developer experience, finishing with advanced patterns for long-lived, evolvable APIs. Each stage builds directly on the vocabulary and mental models of the previous one, so reading in order is essential.
REST Foundations & Mental Models
IntermediateInternalize the architectural constraints of REST, understand why they exist, and build a shared vocabulary for everything that follows.
▸ Study plan for this stage
Pace: 4–5 weeks, ~25–30 pages/day. Read "REST in Practice" (weeks 1–2.5), then "RESTful Web APIs" (weeks 2.5–5). Allocate 2–3 days per week for exercises and reflection.
- REST as an architectural style, not a protocol: the six constraints (client-server, statelessness, cacheability, uniform interface, layered system, code-on-demand) and their rationale
- Hypermedia as the engine of application state (HATEOAS): how links and state transitions replace out-of-band knowledge
- Resource-oriented design: modeling your domain as resources with URIs, not as RPC-style procedures
- HTTP semantics and idempotency: safe methods (GET, HEAD, OPTIONS), idempotent methods (PUT, DELETE), and why this matters for reliability
- Content negotiation and media types: how to design representations that evolve without breaking clients
- The uniform interface constraint: standardized methods, status codes, and self-descriptive messages that enable loose coupling
- Maturity models and pragmatism: Richardson's maturity model and when to apply REST principles versus when to make trade-offs
- Web as a platform: understanding the web's built-in features (caching, proxies, authentication) as design assets, not obstacles
- What are the six architectural constraints of REST, and why does each one matter for building scalable, evolvable systems?
- How does HATEOAS enable loose coupling between client and server, and why is it central to REST rather than optional?
- Explain the difference between resource-oriented and RPC-style API design. Give an example of each and discuss the trade-offs.
- What is the significance of HTTP idempotency? How do safe and idempotent methods improve system reliability and enable caching?
- How does content negotiation allow APIs to evolve without breaking existing clients? What role do media types play?
- Where does your API sit on Richardson's maturity model, and what are the costs and benefits of your current level versus moving up?
- How can you leverage the web's built-in infrastructure (caching, proxies, authentication) as design features rather than working around them?
- Design a simple domain (e.g., a blog, library, or e-commerce system) as a set of resources. Map entities to URIs, identify safe and idempotent operations, and sketch out the state transitions using HATEOAS links.
- Audit an existing API you use (public or internal). Classify it on Richardson's maturity model. Identify which REST constraints it violates and hypothesize why (pragmatism, legacy, or misunderstanding).
- Build a minimal REST API (in your language of choice) for a small domain. Implement at least two resource types, use proper HTTP methods and status codes, and include hypermedia links in responses. Test it with curl or Postman.
- Write a media type definition (or use an existing one like HAL or JSON:API) for one of your resources. Document how clients should interpret links, embedded resources, and state transitions.
- Implement content negotiation in your API: support both JSON and XML (or JSON and a custom format). Verify that a client can request different representations without code changes.
- Trace through a real-world scenario (e.g., placing an order, publishing a post) using your API. Document each request/response and verify that HATEOAS links guide the client through the workflow without hardcoded URLs.
Next up: This stage establishes the mental models and vocabulary needed to evaluate and design APIs; the next stage will apply these principles to concrete patterns, versioning strategies, and real-world trade-offs.
Grounds REST in real HTTP semantics and hypermedia from the start, giving engineers the 'why' behind every constraint before diving into design decisions.
Extends REST fundamentals into practical API design patterns and introduces the Richardson Maturity Model, creating a clear framework for evaluating API quality.
Contracts, Specifications & Tooling
IntermediateDefine APIs through formal contracts using OpenAPI/Swagger, understand design-first workflows, and use specifications to drive consistency across teams.
▸ Study plan for this stage
Pace: 4–5 weeks, ~25–30 pages/day
- OpenAPI/Swagger specification structure: paths, operations, parameters, request/response bodies, and schemas
- Design-first workflow: defining the contract before implementation to drive consistency and reduce rework
- Reusable components and schemas: using $ref, definitions, and component objects to eliminate duplication and enforce consistency
- Documentation as executable specification: how OpenAPI enables automated testing, client generation, and server mocking
- API versioning and evolution strategies within OpenAPI specifications
- Tooling ecosystem: leveraging Swagger UI, Swagger Editor, code generators, and validation tools to enforce contracts
- Security and authentication patterns in OpenAPI: defining OAuth2, API keys, and other auth schemes declaratively
- Real-world API contract patterns: error responses, pagination, filtering, and content negotiation in formal specifications
- How does a design-first approach using OpenAPI differ from a code-first approach, and what are the key benefits for team collaboration?
- What are the main structural components of an OpenAPI specification (paths, operations, parameters, schemas), and how do they work together to define an API contract?
- How do you use $ref and reusable component definitions to maintain consistency and reduce duplication in a large OpenAPI specification?
- What tools and workflows can you use to generate client SDKs, server stubs, and interactive documentation directly from an OpenAPI specification?
- How do you document authentication and authorization schemes (OAuth2, API keys, etc.) in OpenAPI, and why is this important for API consumers?
- What strategies can you employ to version and evolve an API while maintaining backward compatibility, as expressed in OpenAPI specifications?
- Write a complete OpenAPI 3.0 specification for a simple REST API (e.g., a to-do list or blog API) from scratch, including paths, operations, parameters, request/response schemas, and error responses.
- Refactor a basic OpenAPI spec to use $ref and reusable component definitions; measure the reduction in duplication and improve readability.
- Use Swagger Editor to iteratively design and validate an API contract; catch validation errors and fix them in real time.
- Generate a client SDK (using a tool like OpenAPI Generator) from your specification and verify that the generated code matches your intended API design.
- Create a Swagger UI instance for your API specification and share it with a peer; gather feedback on clarity and usability of the documented contract.
- Define multiple authentication schemes (e.g., API key and OAuth2) in an OpenAPI spec and document when each should be used.
Next up: This stage establishes formal, machine-readable contracts that serve as the single source of truth for API behavior; the next stage will build on this foundation to explore how to enforce these contracts through testing, monitoring, and governance practices.
The definitive hands-on guide to the OpenAPI specification, teaching design-first API development and how contracts become the single source of truth for teams.
Versioning, Evolution & Long-Term Maintainability
ExpertMaster strategies for evolving APIs without breaking consumers, handling versioning gracefully, and designing for longevity from day one.
▸ Study plan for this stage
Pace: 4–5 weeks, ~40–50 pages/day, with 2–3 days per week dedicated to hands-on exercises and reflection
- API versioning strategies (URL path, header-based, query parameter, and media type versioning) and their trade-offs
- Backward and forward compatibility: designing changes that don't break existing consumers
- Deprecation policies and graceful sunset strategies for API endpoints and features
- Continuous API management practices: monitoring, governance, and lifecycle management
- Breaking changes: identifying, communicating, and minimizing their impact
- API contracts and semantic versioning: establishing clear expectations with consumers
- Evolution patterns: additive changes, field expansion, and safe refactoring techniques
- Long-term maintainability: designing APIs with future extensibility and flexibility in mind from inception
- What are the main versioning strategies for APIs, and what are the advantages and disadvantages of each approach?
- How do you design an API change that maintains backward compatibility while adding new functionality?
- What constitutes a breaking change, and how should you communicate and manage breaking changes to API consumers?
- What is a deprecation policy, and how do you implement a graceful sunset for deprecated API endpoints?
- How does continuous API management help prevent versioning problems and maintain long-term API health?
- What design principles should you apply from day one to ensure an API can evolve without major rewrites?
- Audit an existing public API (e.g., GitHub, Stripe, or Twitter) and document its versioning strategy, deprecation timeline, and backward compatibility approach
- Design a versioning strategy for a hypothetical API, justifying your choice of method (URL path, header, query parameter, or media type) based on use cases and consumer types
- Create a deprecation policy document for a fictional API, including timeline, communication plan, and migration guidance for consumers
- Refactor an API endpoint to add new functionality while maintaining backward compatibility; document all changes and explain why they don't break existing clients
- Simulate a breaking change scenario: identify the impact, draft a migration guide, and propose a phased rollout plan with clear timelines
- Build a simple API versioning system (e.g., in Node.js, Python, or Go) that supports multiple versions simultaneously and routes requests correctly
- Analyze a real-world API deprecation case study (e.g., Twitter API v1.0 sunset, Facebook Graph API changes) and document lessons learned about communication and migration
Next up: This stage equips you with the strategic and tactical tools to manage API evolution responsibly; the next stage will likely focus on applying these principles to specific domains (e.g., REST, GraphQL, gRPC) or scaling API governance across large organizations.
Addresses the full API lifecycle — versioning, deprecation, governance, and change management — giving engineers a strategic view of how APIs age and evolve.
Synthesizes REST, event-driven, and GraphQL patterns into a unified design process, with strong coverage of backward compatibility and API program strategy.
Discussion
Keep reading
Paths that share books, cover the same subject, or open a related topic.
