Skip to main content

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. 1

    Principles

    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.

  2. 2

    Practical Design

    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.

  3. 3

    Lifecycle

    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.

  4. 4

    Quality

    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.

Frequently asked questions

Ready to practise for interviews?

Practise api design questions with an AI mock interviewer and get feedback on your answers.

More roadmaps