All roadmaps

API Design

Interfaces other developers thank you for.

REST done properly, auth, versioning, error contracts, documentation with OpenAPI, and the GraphQL/gRPC/webhook landscape - the craft of designing interfaces that last.

Your progress0/34 topics · 0%

Progress is saved in this browser.

5 stages34 topics₹0 to follow
Skill certification coming soon

Filled nodes are the focus for this track; outlined ones can wait. Tap a topic to open it and mark it done, learning or skipped.

API Design in 2026Related roadmapsBackend roadmapNode.js roadmapAI Agents roadmapProve it as you goReading is half of it. The free, scoredSoftware Engineer certification coversthe ground this roadmap leads to, and theBackend Engineer job simulation puts itto work on real tickets - evidence arecruiter can check. Mark topics done,learning or skipped as you go; yourprogress carries into the classic view.Software Engineer certificationJob simulationClassic viewKnow the demand before thesyntaxAPI Design in 2026What to learn in 2026REST doneproperlyOpenAPI, auth,versionsAPIs for AI agentsWhich roles use itBackend andfull stackPlatform andintegrationFresher vs switcherWhat companies expectThe hiring barWhat interviewstestProof they verifyWhat gets you hiredA 90-day planProjects thatget readCertification and proofThe conventions that make APIsguessable.REST FoundationsResources & URIsMethods & status codesIdempotencyAPIs that are pleasant underpressure.Contracts & ErgonomicsError designPagination, filtering &sortingVersioningAuth for APIsAn API is its docs.Documentation & GovernanceOpenAPIRate limiting & quotasWebhooksThe landscape, honestlycompared.Beyond RESTGraphQLgRPC (awareness)Real-time APIsFresher or experienced?Both tracks hold every topic. On the Fresher track thefoundations are filled and the later stages are outlined - dothem when a project needs them. On the Experienced track thefoundations are outlined and the later stages are filled. The2026 section at the top applies to both.Prefer a list?The classic view shows the same 4 stages as a sequentialchecklist with time estimates. Your marks are shared betweenthe two views.Open the classic view

Everything on this roadmap

Every stage and topic on the map, in reading order. Click any topic to open it.

1.Know the demand before the syntax

2.The conventions that make APIs guessable.

3.APIs that are pleasant under pressure.

4.An API is its docs.

5.The landscape, honestly compared.

The API Design roadmap, topic by topic

Every topic on the map in reading order, with what to learn and the resources we recommend. Main topics are open; open any subtopic to read it. Select a topic name to open it in the topic panel, where you can track your progress.

  1. 1. Know the demand before the syntax

    API Design in 2026

    2026

    APIs are how software talks to software and, in 2026, how software talks to AI agents. Postman's 2025 State of the API report found 83 percent of organisations working API-first, 65 percent earning revenue from their APIs, a quarter fully API-first - up 12 percent in a year - and one in four developers already designing APIs with AI agents as consumers, while half named rogue or excessive agent calls as their top security concern. API design is therefore a core backend skill and a growing specialism. The four nodes answer what to learn, which roles use it, what companies expect and what gets you hired.

    What to learn in 2026

    Learn REST done properly, then the contract and operations layer - OpenAPI, authentication, versioning, rate limits, errors, pagination - and then the 2026 layer: APIs designed for machine consumers, with the security that implies. The sub-nodes order the three.

    REST done properly

    REST as a discipline, not a habit: resources and their names, the HTTP methods and what each promises, status codes used correctly, consistent error shapes, pagination and filtering, idempotency for anything that mutates, caching headers, and the difference between a well-designed endpoint and a function call over HTTP. Postman's 2025 report's 83 percent API-first figure means most teams now design the interface before the code, and the design review is where a backend engineer's judgement shows. Learn by writing the contract for a real resource before implementing it.

    OpenAPI, auth, versions

    The operational layer turns an endpoint into a product: an OpenAPI document that generates clients and documentation, authentication with API keys or OAuth and scopes, versioning without breaking consumers, rate limits and quotas, structured errors, webhooks, and contract tests that fail when the shape changes. Postman's 2025 report found 65 percent of organisations earning revenue from APIs, which is why these details are what buyers and partners judge. GraphQL and gRPC are worth knowing as alternatives for specific shapes of problem; REST with a good contract is still the default.

    APIs for AI agents

    AI

    Agents call APIs differently from people: in loops, in parallel, with imperfect understanding of the documentation, and sometimes without authority. Postman's 2025 report found 24 percent of developers already designing for AI agents and 51 percent naming unauthorised or excessive agent calls their top security worry; Gartner expects a third of enterprise applications to include agentic AI by 2028. Designing for agents means precise, machine-readable contracts, idempotency everywhere, strict rate limits and scopes, clear error messages an agent can act on, and tool descriptions - increasingly through the Model Context Protocol - that say exactly what an endpoint does and does not do.

    Which roles use it

    Backend and full stack engineers design APIs as part of every service; platform and integration engineers design them as the product. The sub-nodes name both groups and lay out the fresher and switcher routes.

    Backend and full stack

    Every backend and full stack engineer designs APIs: the contract between a service and its clients is the most consequential design decision most of them make, and the Stack Overflow 2025 survey's most common developer types are exactly these. The Backend roadmap assumes this skill; the Node.js and Java roadmaps implement it in their stacks. In interviews for these roles the API design conversation is where seniority is judged, because it exposes how you think about consumers, failure and change.

    Platform and integration

    Platform and integration engineers make the API the product: public APIs, partner integrations, internal platforms that other teams build on, and the developer experience around them - documentation, SDKs, sandboxes, support. Postman's 2025 report's 25 percent of fully API-first organisations is where these roles concentrate, in fintech, SaaS, logistics and the companies now exposing their products to AI agents. The work rewards clarity, empathy for the consumer and an eye for what breaks when something changes.

    Fresher vs switcher

    A fresher should deploy one API with a public OpenAPI page before applying for backend roles; HackerRank's 2025 report found early-career hiring the hardest hit, and a contract a reviewer can read and call is a rare, visible proof. A switcher from frontend work has consumed many APIs and should design one; a switcher from QA has tested them and should build the contract tests. On this map freshers get the REST basics filled and the advanced stages outlined; experienced learners get the reverse.

    What companies expect

    Companies expect an API that a stranger can use from its documentation alone: consistent resources, correct status codes, predictable errors, pagination, authentication, versioning and a published contract. The sub-nodes cover the bar, the interview and what gets verified.

    The hiring bar

    The bar is an API usable from its documentation alone: consistent naming, correct methods and codes, predictable errors, pagination, authentication with scopes, a version strategy, rate limits, an OpenAPI document that matches the implementation and tests that prove it. The Work Trend Index found 66 percent of leaders unwilling to hire without AI skills; API teams expect assistants used to draft the contract and the engineer accountable for every edge an agent could hit.

    What interviews test

    Expect to design an API live - for a bookings, payments or inventory domain - and defend the resources, the error cases, pagination, versioning and authentication; to review a bad contract and fix it; and to discuss what changes when the consumer is an agent. HackerRank's 2025 report says 66 percent of developers prefer practical assessments and that they are now the standard. The strongest answers name the consumer and the failure before naming the endpoint.

    Proof they verify

    Reviewers call your API from its documentation: a deployed service with a public OpenAPI page, authentication, a health endpoint, sensible errors and contract tests in the repository beats any description; a note on how it handles agent consumers - idempotency, limits, scopes - is now a differentiator. Pair it with a verified certification for the stack you built it in; OneRoadmap's are free and verifiable.

    What gets you hired

    A deployed API with a public OpenAPI page that a reviewer can call, a repository with tests against the contract, and a clear account of the design decisions. The sub-nodes give the ninety-day plan, the projects that get read and the proof that counts.

    A 90-day plan

    Month one: REST properly, with the contract for a real domain written in OpenAPI before any code. Month two: the API implemented in your stack with authentication, pagination, errors, versioning and contract tests, deployed with a public documentation page. Month three: rate limits, webhooks and an agent-ready tool description for the same API, a readme on the design decisions, and twenty targeted applications a week with the live documentation linked.

    Projects that get read

    Projects that get read are APIs a stranger can use: a bookings or inventory API with a public OpenAPI page, scoped keys, pagination and idempotent writes; a webhook delivery system with retries and signatures; a thin integration layer over two public APIs with a clean unified contract; an agent-callable tool server with precise descriptions and strict limits. Each has a live base URL, tests and a readme. Postman's 2025 report says one in four developers now design for agents - a project that shows you can is early proof.

    Certification and proof

    Proof is verifiable: a running API with public documentation, a GitHub profile with the contract and its tests, a verified certification in the stack, and a short account of how you used AI tools in the design. The API engineers who get replies are the ones whose documentation a reviewer can read and whose endpoint answers.

  2. 2. The conventions that make APIs guessable.

    REST Foundations

    The conventions that make APIs guessable.

    Time: about 1-2 weeks. Topics: Resources & URIs · Methods & status codes · Idempotency.

    Resources & URIs

    Optional on the Experienced track

    Nouns not verbs, plural collections, nesting limits - URL design as information architecture.

    Methods & status codes

    Optional on the Experienced track

    GET/POST/PUT/PATCH/DELETE semantics and the status codes that tell clients the truth.

    Idempotency

    Optional on the Experienced track

    Safe retries via idempotent methods and idempotency keys - the difference between one charge and three.

  3. 3. APIs that are pleasant under pressure.

    Contracts & Ergonomics

    APIs that are pleasant under pressure.

    Time: about 1-2 weeks. Topics: Error design · Pagination, filtering & sorting · Versioning · Auth for APIs.

    Error design

    Consistent error envelopes, machine-readable codes and human messages - errors as UX.

    Pagination, filtering & sorting

    Cursor vs offset, filter grammars and stable ordering - list endpoints that scale.

    Versioning

    URI vs header versioning, additive changes and deprecation policy - evolving without breaking.

    Auth for APIs

    API keys, OAuth 2.0 flows and scopes - matching the scheme to the consumer.

  4. 4. An API is its docs.

    Documentation & Governance

    An API is its docs.

    Time: about 1 week. Topics: OpenAPI · Rate limiting & quotas · Webhooks.

    OpenAPI

    Spec-first design, generated docs and client SDKs - one source of truth for the contract.

    Rate limiting & quotas

    Protecting the service and communicating limits (429s, headers) fairly.

    Webhooks

    Push over poll: signatures, retries and ordering - designing the reverse API.

  5. 5. The landscape, honestly compared.

    Beyond REST

    The landscape, honestly compared.

    Time: about 1 week. Topics: GraphQL · gRPC (awareness) · Real-time APIs.

    Build: Design a public API. Write a full OpenAPI spec for a product of your choice: resources, errors, auth, pagination and a deprecation policy.

    GraphQL

    Optional on the Fresher track

    Client-driven queries, N+1 pitfalls and when a graph beats resources.

    gRPC (awareness)

    Optional on the Fresher track

    Contract-first binary RPC for service-to-service - where REST's overhead matters.

    Real-time APIs

    Optional on the Fresher track

    WebSockets and server-sent events - choosing a push transport per use case.

Prove it as you go

Reading is half of it. The free, scored Software Engineer certification covers the ground this roadmap leads to, and the Backend Engineer job simulation puts it to work on real tickets - evidence a recruiter can check. Mark topics done, learning or skipped as you go; your progress carries into the classic view.

Fresher or experienced?

Both tracks hold every topic. On the Fresher track the foundations are filled and the later stages are outlined - do them when a project needs them. On the Experienced track the foundations are outlined and the later stages are filled. The 2026 section at the top applies to both.

Prefer a list?

The classic view shows the same 4 stages as a sequential checklist with time estimates. Your marks are shared between the two views.

Frequently asked questions

What is API design and why is it a separate skill?

API design is deciding how software talks to software: the resources, the methods, the status codes, the errors, pagination, authentication, versioning and the published contract. It is separate because it is the most consequential design decision most backend engineers make and the hardest to change once consumers depend on it. Postman's 2025 report found 83 percent of organisations working API-first.

REST, GraphQL or gRPC?

REST with a good OpenAPI contract is still the default and what most jobs expect. GraphQL suits clients that need flexible queries over a graph of data; gRPC suits service-to-service calls where performance and strict contracts matter. Learn REST properly first; the others are worth understanding as alternatives for specific shapes of problem.

What does designing APIs for AI agents mean?

Agents call APIs in loops, in parallel, with imperfect understanding and sometimes without authority. Postman's 2025 report found one in four developers already designing for them and half naming rogue agent calls their top security concern. Designing for agents means precise machine-readable contracts, idempotency everywhere, strict limits and scopes, clear errors an agent can act on, and tool descriptions that say exactly what an endpoint does.

Do I need to know OpenAPI?

Yes. An OpenAPI document is the contract: it generates documentation and clients, it is what contract tests check, and it is what a reviewer reads first. Write it before the code for a real resource and you will learn most of API design in the process.

How do I version an API without breaking consumers?

Add, do not change: new fields and endpoints are safe, renamed or removed ones are not. Version in the path or a header only when a breaking change is unavoidable, keep the old version running for a stated period, and publish the deprecation. Most breaking changes can be avoided by designing the first version carefully.

How long does it take to learn API design?

REST done properly takes a few weeks of designing and building real contracts; the operational layer - authentication, versioning, limits, webhooks, contract tests - a few more; the judgement comes from reviewing bad APIs and fixing them. Nobody can promise a timeline. A deployed API a stranger can use from its documentation alone is the evidence.

Will AI design the APIs?

Assistants draft contracts well and miss the edges - idempotency, limits, the error an agent will loop on. The engineer who names the consumer and the failure before naming the endpoint, and who tests the contract, is the one whose API survives. As more consumers become agents, that judgement is worth more.

How do I prove API design skills without job experience?

A deployed API with a public OpenAPI page, scoped keys, pagination, idempotent writes, sensible errors and contract tests in the repository; a webhook system with retries and signatures; an agent-callable tool server with precise descriptions and strict limits. A reviewer who can use your API from its documentation alone has all the proof they need.