Designing an API End to End

Each earlier topic in this subject settled one kind of decision: resources and paths, methods, status codes, contracts, errors, caching, retries, security and evolution. Designing a real API means making all of them for one feature, in an order where each decision rests on the one before, and then checking the result before any client depends on it.

The topic opens with a walkthrough that turns five user stories for an orders API into endpoints and a contract, naming the topic behind each decision. Two cards cover what a working API needs around its endpoints: request ids and trace context, so a failure can be found, and documentation people can use. A review checklist gathers the subject's rules into twelve questions, an example applies it to one badly designed endpoint, and an exercise designs an API for event tickets from its requirements.

It builds on every earlier topic in this subject, and names the one each decision comes from.

By the end you can derive endpoints from requirements, review an endpoint against a checklist, pass trace context between services, and assemble the contract for one feature.