APIs with Express · Chapter 24 of 29
Project: the orders API
By the end of this chapter you can build a complete JSON API on your own: validation, a status machine, pages, one error shape and retries that are safe. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: Projects
- 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
Meera has promised three partner cafés a working orders API by Friday. Ravi needs every order to move placed, brewing, ready, delivered, one step at a time: nobody delivers a chai that was never brewed. Blue Tokai's developer has two complaints already. Errors come back in four different shapes, and when their Wi-Fi drops they send the order again, and the customer pays twice.
Each chapter so far built one piece. Put together without a plan, every route answers its errors its own way, a bad request gets one complaint at a time, and a retry is a second order. This chapter is one app, designed as a whole.
What you build: 6 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
GET /menu and GET /menu/:id: the menu, read from the store
In createApp({ store }), GET /menu answers store.menu as JSON, every item in the store's order. With ?available=true it keeps only the available items: masala-chai, cutting-chai and bun-maska.
GET /menu/:id answers that one item ({ id: 'bun-maska', name: 'Bun maska', price: 35, available: true }), or 404 with { error: { code: 'not_found', message: 'Menu item not found' } } (/menu/samosa).
Read store.menu on every request: an item pushed into store.menu after createApp() is found straight away.
- Task 2
POST /orders and GET /orders/:id: priced from the menu
POST /orders takes { customer, items: [{ id, qty }] }. A good order answers 201 with a Location header /orders/<id> and { id, customer, items: [{ id, name, qty, price }], total, status: 'placed' }: customer trimmed (' Ravi ' becomes 'Ravi'), name and price from the menu (a price the client sends is ignored and not copied), total the sum of price times qty (2 masala chai and 1 bun maska make 115). The order is pushed into store.orders. Its id is one more than the biggest id in store.orders (1 for an empty store, 8 when the store holds an order 7).
A bad order is not saved and answers 400 with { error: { code: 'validation_failed', message: 'Validation failed', details } }, where details lists every problem in this order: 'customer is required' (missing, not text, or blank); 'items must be a non-empty array' (and then nothing about the lines); then for each line i, 'items[i].id is not on the menu' or else 'items[i].id is not available', and then 'items[i].qty must be a whole number from 1 to 10' (0, 1.5 and 11 all fail).
GET /orders/:id answers the order, or 404 with { error: { code: 'not_found', message: 'Order not found' } }.
- Task 3
PATCH /orders/:id/status: one step at a time
PATCH /orders/:id/status takes { status }. Orders move placed, brewing, ready, delivered, only to the very next status.
Checked in this order: an order that does not exist answers 404 with code 'not_found'; a status that is not one of the four answers 400 with { error: { code: 'validation_failed', message: 'Validation failed', details: ['status must be one of placed, brewing, ready, delivered'] } }; any other move (skipping, going back, the same status again, or anything after delivered) answers 409 with { error: { code: 'invalid_transition', message: 'Cannot move order 1 from placed to ready' } }, naming the order's id, its status now and the status asked for.
A good move changes the order in the store and answers 200 with the whole updated order.
- Task 4
GET /orders: filters and pages
GET /orders answers { data, page, limit, total, totalPages }. page defaults to 1 and limit to 10, both answered as numbers. ?status= keeps orders with that status, and ?customer= keeps orders whose customer matches ignoring case (ravi finds Ravi, ravi and RAVI). The matches keep the store's order; data is one page of them, total counts all the matches and totalPages is total divided by limit, rounded up. A page past the end has data [].
Bad input answers 400 with code 'validation_failed', message 'Validation failed' and details listing, in this order, each that applies: 'status must be one of placed, brewing, ready, delivered'; 'page must be a positive whole number' (0 or two); 'limit must be a whole number from 1 to 50' (500 or 2.5).
- Task 5
One error shape: unknown routes, broken JSON and crashes
Every error answers JSON as { error: { code, message } }, with details only on validation errors.
A route that does not exist answers 404 with { error: { code: 'not_found', message: 'Route DELETE /kitchen not found' } }, naming the method and the path.
A body that is not valid JSON answers 400 with { error: { code: 'invalid_json', message: 'Body is not valid JSON' } }.
Any other error, such as a store whose menu throws 'connection to db-1 refused', answers 500 with { error: { code: 'internal', message: 'Something went wrong' } }, and the real message never appears in the answer.
- Task 6 · interview question
Interview: POST /orders, safe to retry with an Idempotency-Key
POST /orders may carry an Idempotency-Key header. The first order with a key is placed as usual (201, no Idempotent-Replayed header).
A retry with the same key and the same body (the same JSON) creates nothing: it answers 201 with the saved order again, the same Location (/orders/1) and the header Idempotent-Replayed: true.
The same key with a different body answers 422 with { error: { code: 'idempotency_mismatch', message: 'Idempotency-Key was used with a different body' } }.
Another key, or no key at all, places a new order every time. Each createApp() remembers its own keys.
What you will learn
- One error shape: errors thrown anywhere, answered by one error handler at the end.
- Validation that reports everything: every problem in one answer.
- A status machine: allowed moves in a table, and 409 for the rest.
- Pages and idempotency keys: lists that come in pages, and retries that do not create a second order.
More in Projects
Build "Project: the orders API" 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.