Module · Backend Engineer
API Design
Contracts that survive their first client - resources, errors and version after version.
TOPIC 01
Resource Modelling
Model the domain first, then expose it - and page through the result properly.
What you'll practice
- Write an OpenAPI Contract — guided · beginner
- Paginate Without Breaking Clients — practice · intermediate
A command you'll meet
cat ~/api/openapi/orders.yamlThe contract is the product. Open the task below for the full walkthrough.
Hands-On Tasks in This Topic (2)
Write an OpenAPI Contract
The specification is how clients are generated and how nobody has to ask what the endpoint returns. Write it for the orders collection.
Paginate Without Breaking Clients
Offset pagination dies at scale and breaks when rows are inserted. Write the cursor based contract and the parameters that go with it.
TOPIC 02
Errors & Versioning
One error shape for every failure, and a plan for the version you will break someday.
What you'll practice
- Standardise the Error Envelope — practice · intermediate
- Version Without Breaking Clients — challenge · advanced
A command you'll meet
cat ~/api/errors.mdClients only handle the errors you document. Open the task below for the full walkthrough.
Hands-On Tasks in This Topic (2)
Standardise the Error Envelope
Every endpoint fails eventually. Give them all one shape so a client can handle the failure with one code path.
Version Without Breaking Clients
You will ship a breaking change. Decide now how versions are named, how they are deprecated and when they are switched off.