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.

  1. 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.

  2. 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' } }.

  3. 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.

  4. 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).

  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.

  6. 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.