Turning Requirements Into Endpoints: An Orders API

Five user stories become resources, paths, methods, codes, errors and a contract, one decision at a time.

Designing an API from requirements works in a fixed order: find the nouns, which become resources; give them paths; choose methods; choose status codes; settle the error shape, caching and retry keys; then write the contract and review it. Each step uses an earlier topic in this subject. Here it is applied to five user stories for an orders feature.

A customer creates an order and adds items to it before submitting.
A customer sees their own orders, newest first.
A customer submits an order and pays, exactly once, even on a poor connection.
A customer may cancel an order within an hour of submitting it.
A warehouse system is told when an order is submitted.

Each requirement becoming its endpoint, and the decision behind it

InputFive user stories for an orders feature

Create and add items
1. POST /orders → 201resource
2. POST /orders/{id}/items → 201
Nouns order and item become collections, items nested under their order, from the topic on resource-oriented design. 201 with Location, from the topic on status codes.
See own orders
1. GET /orders?sort=-createdAt&limit=20scoped
Scoped to the caller from the token, never a userId in the query, from the topic on protecting an API. Cursor pagination, from the topic on resource-oriented design.
Submit and pay once
1. POST /orders/{id}/submission
2. Idempotency-Key headerretry-safe
Submitting is an action modelled as a resource; a key makes a retried payment safe, from the topic on idempotency keys.
Cancel within an hour
1. POST /orders/{id}/cancellation → 201 or 409rule
409 with a problem details body after the hour, from the topic on error responses.
Tell the warehouse
1. Webhook order.submitted, signedasync
Pushed rather than polled, signed and deduplicated by event id, from the topic on asynchronous APIs.

ResultSeven operations, every one traced to a story and to the rule that shaped it, ready to write as an OpenAPI document.

Then the cross-cutting decisions. Authentication by OAuth bearer token, with scopes orders:read and orders:write. Errors as problem details everywhere. ETag and If-Match on order updates, so two edits cannot overwrite each other. A rate limit per client, with 429 and Retry-After. Path versioning, starting at /v1.

Then the contract. Write the OpenAPI document from these decisions: every path, method, request and response schema, error, security scheme and example. It becomes the source of mocks, client code, tests and the reference documentation.

Then the review. Run the checklist in the topic's card on reviewing a design against the contract, before any client is built against it. A problem found here costs an edit; found after release, it costs a version.

← → move through sections and cards