API Design roadmap
Design web APIs that are predictable to call, safe to retry, secure by default and easy to evolve.
At a glance
- Stages5
- Steps20
- Core steps13
- Optional or alternative7
- Linked courses2
How to use this roadmap
Work through the stages in order. Core steps are the ones everyone on this path needs; optional steps add depth when you have time, and alternatives are other ways to the same skill, so pick one. Steps with a course link to a free course from LearnerMap Academy.
Members of LearnerMap Academy can mark each step as learning, done or skipped, and see how far along the path they are.
HTTP foundations
Methods and resources
CoreModel nouns as resources and use methods for what they promise.
Course: API DesignHTTP request methods (MDN)RFC 9110: HTTP semantics
Status codes
CoreReturn codes that tell clients what happened and what to do next.
Content negotiation
CoreAgree on formats and languages through headers.
Caching
OptionalLet clients and proxies reuse responses safely.
Designing resources
Naming and structure
CorePick consistent names, collections and identifiers before writing handlers.
Pagination and filtering
CorePage large collections with stable cursors and simple filters.
Errors people can act on
CoreReturn a stable machine code with a message written for people.
Versioning and compatibility
CoreAdd without breaking, and plan how breaking changes will roll out.
Reliability
Idempotency
CoreMake retries safe so a timeout never creates a duplicate order.
Optimistic concurrency
CoreDetect lost updates with versions or entity tags.
Rate limiting
OptionalProtect the service and tell clients when to try again.
Events and webhooks
OptionalNotify other systems of changes and describe event-driven APIs.
Security
Authentication
CoreIdentify callers with sessions, tokens or delegated access.
Object-level authorization
CoreCheck that the caller may touch this specific record on every request.
Input validation
CoreValidate shape, size and type at the boundary, and drop unknown fields.
Cross-origin requests
OptionalAllow browsers on other origins exactly the access they need.
Describing and choosing styles
OpenAPI
CoreDescribe endpoints and schemas so docs and clients stay in sync with the code.
GraphQL
AlternativeExpose a typed graph that clients query for the fields they need.
gRPC
AlternativeUse generated, strongly typed clients for service-to-service calls.
Real-time APIs
OptionalPush updates with WebSockets or server-sent events.
Learning with LearnerMap Academy
LearnerMap Academy runs its learning on LearnerMap, a free platform for organisations. Every course here is free for members of LearnerMap Academy: sign in with the email address LearnerMap Academy knows you by, or with a passkey, and the course opens in your own plan.
Your plan holds at most 3 courses in progress at a time, so you finish what you start before pulling in the next one. Lessons open in order, your progress is saved as you complete each one, and every course ends with a quiz; passing it adds a certificate to your record.
Not a member yet? Ask LearnerMap Academy to invite you. Lesson content, quizzes and everyone’s progress stay private to members; these public pages show only what LearnerMap Academy chose to publish.