Practice: Writing the Contract for Create Order

Write the request, the 201 response, two error responses and the list response for an order endpoint.

Writing a whole endpoint's contract applies every convention at once. A shop's API needs POST /orders. An order has one or more items, each a product code and a quantity from 1 to 99, an optional delivery note, and an optional delivery date that must be in the future. The server sets the id, the status open, the creation time and the total in euros.

Write:

A valid request body.
The success response, with its status code and headers.
The response to a body that is not valid JSON.
The response to a delivery date in the past.
The response to GET /orders?limit=2, when more orders exist.

Show one good contract

text

1. POST /orders
   Content-Type: application/json
   {"items": [{"sku": "pen-blue", "quantity": 3}],
    "note": "Leave at reception",
    "deliverOn": "2026-10-12"}

2. 201 Created
   Location: /orders/43
   {"id": "43", "status": "open",
    "createdAt": "2026-10-07T14:30:00Z",
    "items": [{"sku": "pen-blue", "quantity": 3}],
    "note": "Leave at reception", "deliverOn": "2026-10-12",
    "total": {"amount": 597, "currency": "EUR"}}

3. 400 Bad Request
   {"error": "malformed-json", "detail": "Unexpected end of input"}

4. 422 Unprocessable Content
   {"error": "invalid-value", "field": "deliverOn",
    "detail": "The delivery date must be in the future"}

5. 200 OK
   {"items": [{"id": "43", ...}, {"id": "42", ...}],
    "nextCursor": "b3JkZXI6NDI",
    "links": {"next": "/orders?cursor=b3JkZXI6NDI&limit=2"}}

An illustrative set of request and responses for the order endpoint

The id is a string, the time has an offset, the total is in cents with a currency, and the list is an object with a cursor. A standard shape for the error bodies is the next topic's subject.

← → move through sections and cards