API Design Roadmap 2026
Design great APIs: REST, resources, contracts, errors, versioning, pagination, documentation and governance.
4 stages · 7 units · Intermediate · about 50 hours · Last reviewed 19 November 2026
What is a api design?
API design is the practice of defining how software systems talk to each other over an interface: which resources exist, how requests and responses look, how errors are reported and how the interface changes over time. Good design makes an API predictable for client developers and safe to evolve. REST over HTTP is the most common style.
Step-by-step api design roadmap
- 1
Principles
Beginner · about 20 hours
Think in resources.
- Concepts
API design concepts are the foundations behind every interface: the main API styles such as REST, GraphQL and RPC, and resource modelling, which means choosing nouns, identifiers and relationships that clients will call. This unit comes first, since naming and structure are the hardest things to change later.
- Contracts
An API contract is the agreed shape of every request and response, including field names, types, status codes and the format of errors. Contract design means making payloads consistent and errors machine-readable, for example with problem details, so clients can handle failures without guessing from message text.
- Concepts
- 2
Practical Design
Intermediate · about 15 hours
Everyday decisions.
- Collections
Collection endpoints return many items, so their design covers listing, filtering, sorting, searching and pagination, plus handling bulk and long-running operations. Cursor and offset pagination, the 202 Accepted pattern and batch requests all belong here, and they decide whether an API stays fast as data grows.
- Security and Limits
API security and limits cover who may call an API and how much they may call it: authentication with API keys, OAuth 2.0 or JWTs, authorisation per resource, and rate limiting with quotas. The design questions are which scheme fits which client and how limits are communicated back to callers.
- Collections
- 3
Lifecycle
Intermediate
Evolve safely.
- Versioning
API versioning is the set of rules for changing an API without breaking existing clients. It covers what counts as a breaking change, how versions are expressed in URLs or headers, and how deprecations are announced with sunset dates. The goal is to let providers evolve while consumers migrate on their own schedule.
- Documentation
API documentation is the written and machine-readable description of an API, centred on the OpenAPI specification, a YAML or JSON file that lists paths, parameters, schemas and responses. It feeds reference pages, mock servers and generated client code, and it works best when guides and examples sit beside it.
- Versioning
- 4
Quality
Advanced
Test and govern.
- Quality
API quality and governance is the work of keeping many APIs consistent and correct over time: contract tests, linting of OpenAPI files against a style guide, review processes and checks for breaking changes in CI. It turns individual good designs into a standard that a whole organisation can follow.
- Quality
Frequently asked questions
Ready to practise for interviews?
Practise api design questions with an AI mock interviewer and get feedback on your answers.