HTTPJSONIntermediate~3h

REST API Design

Design it, then defend it

Most arguments about an API are two people trading preferences. This is the other way: take the requirement, find the constraint on the surface, and let that decide. Names, changes that break nobody, moving lists, errors a client can act on, retries that cannot charge twice — then a contract of your own.

Start this project See the modules

Modules: 7
Drills: 13
Build steps: 4
Time: ~3h

Walk out able to

Review an API you have never seen — its names, its next release, its list endpoints, its errors and its retries — and say what is wrong and which rule says so.

What you drill

Resources and names

The noun inside the verb, and path against query.

Changes that do not break

What the contract covers, and how to ship it additively.

Lists that keep moving

Rows seen twice, rows missed, and the scheme to use.

Errors and safe retries

Bodies a client can act on, and idempotency keys.

The pitch

What you practise, and what you leave with

A one-page interface contract for a service of your own: five endpoints, its errors, its paging, and what you promise not to change.

You will practise

Resources, naming, path against query
Breaking changes and additive repairs
Offset drift, cursors, paging cost
Error bodies and idempotency keys

Afterwards you can

Put an operation that is a verb on a resource
Say whether a change breaks its clients
Count the rows a paged reader missed
Make a timed-out create safe to send again

Modules

7 modules, 24 items

Lessons explain one idea. Drills repeat it until it sticks. Build steps make something that exists afterwards.

1
Name the resources
~36 min
Put an operation on a resource, including the ones that arrive as verbs.
- LessonWhy the address you pick matters5 min
- LessonModel the verb as a resource10 min
- DrillPut the operation on a resource12 min
- DrillDecide path or query9 min
2
Change without breaking clients
~22 min
Classify a change against the contract in force, then ship it additively.
- DrillSay whether the change breaks10 min
- DrillShip it without a new version12 min
3
Page a list that keeps moving
~34 min
Count what a reader duplicates, then pick the scheme the requirement forces.
- DrillCount what the reader missed13 min
- DrillPick the paging scheme12 min
- DrillSize the paged job9 min
4
Errors a client can act on
~34 min
Put each fact where a client can reach it, and fault the bodies that hide it.
- DrillPlace the fact in the body9 min
- DrillCount what the 422 owes12 min
- DrillFault the error response13 min
5
Make a retry harmless
~33 min
Decide what may be repeated, then make what may not be into something that can.
- DrillDecide if it may be sent again9 min
- DrillRun the idempotency table13 min
- DrillChoose the key, or none11 min
6
Write a contract of your own
~25 min
Commit a real interface to paper: endpoints, lists, errors, promises and keys.
- Build stepName your service’s five endpoints7 min
- Build stepState what your lists do6 min
- Build stepSay how it fails, and what holds6 min
- Build stepMark your own contract6 min
7
Review five surfaces cold
~20 min
One decision from each module, on five services nobody has walked you through.
- LessonAddress the hold that must be listed4 min
- LessonFind the change that cannot ship4 min
- LessonCount what the sync copied twice4 min
- LessonFault the refusal a till cannot act on4 min
- LessonExplain the retry that billed twice4 min