APIs with Express · Chapter 12 of 29

REST design

By the end of this chapter you can design an API that partners can guess: honest status codes, filters and pages, and safe retries. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: The Tapri API
  • 6 tasks
  • Express
  • In the all labs plan

The first 2 chapters of APIs with Express are free. This one comes with the all labs plan.

Why you need this

Blue Tokai's developer has complaints about Tapri's partner API. Placing an order is POST /createOrder, cancelling one GET /cancelOrder?id=4, and every answer is a 200, even on failure. When their app retried a slow order in the 4 pm rush, Ravi's kitchen made the same ten masala chais twice.

So far, every feature is one more URL verb (/cancelOrder, /changeOrderQty), each with its own docs. A 200 hiding an error looks like success, and a retried POST makes a second order.

What you build: 6 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    GET /orders: filters and one page at a time

    In createApp, finish GET /orders. It answers 200 with { data, page, limit, total }: data is one page of orders in id order, and total counts every order that passed the filters, not only this page.

    ?status=ready and ?customer=Third%20Wave keep only the orders whose status or customer is exactly that, and both can be used together. ?page and ?limit choose the page: page defaults to 1, limit to 10, and a limit over 50 is cut to 50 (the answer then says limit 50). A page past the end answers 200 with data [].

    A page or a limit that is not a whole number above zero (0, abc, -3, 2.5) answers 400 with { error: 'page and limit must be positive whole numbers' }.

    With the five starting orders, GET /orders?status=ready&limit=2 answers data [order 1, order 4] with page 1, limit 2 and total 3, and page=2 of the same gives [order 5].

  2. Task 2

    GET /orders/:id: one order, or a 404

    Add GET /orders/:id. It answers 200 with the order whose id matches, exactly as it is stored: GET /orders/3 gives { id: 3, customer: 'Blue Tokai', item: 'bun-maska', qty: 3, status: 'delivered' }.

    An id with no order answers 404 with { error: 'Order <id> not found' }, the id as it was written in the URL: GET /orders/99 gives { error: 'Order 99 not found' }, and GET /orders/abc is a 404 too.

  3. Task 3

    POST /orders: 201 and a Location header

    Add POST /orders. The JSON body is { customer, item, qty }: customer and item must be non-empty text and qty a whole number above zero. The new order is exactly { id, customer, item, qty, status: 'placed' }, with ids going on from 6 (then 7 and so on). It is added to the list, and the answer is 201 with that order and a Location header of /orders/<id>, for example /orders/6, which GET /orders/:id then answers.

    A missing or bad field (qty 0, no qty, no customer, an empty body) answers 400 with { error: 'customer, item and qty are required' } and adds nothing. A POST with no body at all is a 400 too, not a crash.

  4. Task 4 · interview question

    Interview: PUT replaces an order, PATCH changes part of it

    Add PUT /orders/:id and PATCH /orders/:id. Both answer 200 with the order as it is now, and an unknown id answers 404 with { error: 'Order <id> not found' }. Neither ever changes the id: it comes from the URL, even if the body has one.

    PATCH changes only the fields the body sends, out of customer, item, qty, status and note, and keeps the rest: PATCH /orders/1 with { status: 'delivered', id: 99 } answers order 1 with status delivered and its note 'less sugar' still there.

    PUT replaces the whole order with { id, customer, item, qty, status } from the body, plus note only if the body sends one, so a note it leaves out is gone. Sending the same PUT twice leaves the same order. A PUT body without valid customer, item, qty and status answers 400 with { error: 'PUT needs customer, item, qty and status' } and changes nothing.

  5. Task 5

    DELETE /orders/:id: 204, then 404

    Add DELETE /orders/:id. It removes the order and answers 204 with an empty body; after that GET /orders/2 is a 404 and the list no longer has it ([1, 3, 4, 5]).

    Deleting the same order again answers 404 with { error: 'Order 2 not found' }. A new app from createApp() still has all five orders.

  6. Task 6

    POST /orders: safe to retry with an Idempotency-Key

    Make POST /orders remember the Idempotency-Key request header. The first POST with a key creates the order as in task 3. A POST that repeats a key answers what the first one did, 201 with the same body and the same Location, and creates nothing: two POSTs with the key tw-4pm-1 leave 6 orders, not 7.

    A different key creates a new order (the next id). Without the header, every POST creates a new order, as before. Each app remembers only its own keys.

What you will learn

  • Resources and methods: one URL per thing; the method says the action.
  • Filters and pages: the query string narrows a list.
  • PUT versus PATCH: replacing a resource, or part of it.
  • Idempotency: which requests are safe to repeat, and how an Idempotency-Key makes a create safe.

More in The Tapri API

Build "REST design" yourself

Partner cafés want Tapri’s menu online by Friday: you build its API. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of APIs with Express are free. This one comes with the all labs plan.