APIs with Express · Chapter 27 of 29
Project: the API gateway
By the end of this chapter you can put one Express app in front of several services, forward each request to the right one, and answer clearly when a service is slow or down. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: Projects
- 5 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
Tapri has grown out of one app. The menu now lives in its own service, which Anjali's team deploys twice a day, and orders live in another, which Ravi's team never restarts during the 4 pm rush. Meera wants the partner cafés to see one address, api.tapri.in, and nothing behind it.
Your routers answer requests themselves; here the answer comes from another server. And a gateway that forwards naively is worse than none: one service that is down crashes it, and every café loses both services at once.
What you build: 5 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
createApp: each prefix to its service, and a 404 for the rest
createApp({ upstreams, timeoutMs }) gets the two services' base URLs, such as upstreams.menu = 'http://127.0.0.1:41234'. Use node:http (or fetch), no proxy package and no body parser.
A request under /api/menu goes to the menu service and one under /api/orders to the orders service, with the prefix taken off and the rest of the path and the query kept: /api/menu/items?veg=true asks the menu service for /items?veg=true, /api/menu asks it for /, and /api/orders/orders/3 asks the orders service for /orders/3. The service's status, headers and body come back to the client unchanged, its own errors included (a 404 { error: 'no such item' } stays exactly that).
Every other path answers 404 with { error: 'No route for <METHOD> <path>' }, for example { error: 'No route for GET /api/payments' } and { error: 'No route for POST /api/menux' }, and calls no service.
- Task 2 · interview question
Interview: forward method, body and headers, but not hop-by-hop ones
The service gets the same method (POST, PUT and DELETE too), the body exactly as sent, byte for byte, whatever its Content-Type (JSON with odd spacing such as '{ "item": "masala-chai", "qty": 2 }', plain text, or no body at all), and the client's request headers, such as Content-Type, Authorization and X-Cafe.
The headers in HOP_BY_HOP (Proxy-Authorization and TE among them) and any header named in the Connection header are not sent on, and Host is the service's own host (127.0.0.1 and its port), not the gateway's. The service's answer comes back with its status and headers (a 201 with Location: /orders/9 and X-Upstream: orders), again without hop-by-hop ones.
- Task 3
createApp: the service's own Host, and a request id both ways
Every forwarded request carries Host set to the service's own host, and an X-Request-Id. An incoming X-Request-Id of 1 to 64 characters, all letters, digits or dashes ('blue-tokai-77'), is kept. Otherwise ('a b c', or no header) the gateway makes one: 'gw-1', 'gw-2' and so on, counting only the ids it makes, from 1 for each createApp().
The same id is sent to the service and back to the client in the X-Request-Id response header, on every response, the 404 for an unknown path included: a fresh app answers GET /api/menu/items with gw-1, keeps blue-tokai-77, answers 'a b c' with gw-2 and GET /nowhere with 404 and gw-3.
- Task 4
createApp: give up on a slow service with a 504
When a service has not answered within timeoutMs milliseconds (2000 by default), the gateway answers 504 with { error: 'Upstream timed out', upstream: 'menu' }, naming the service, still with its X-Request-Id, and stops waiting for that service. Not a moment before: with timeoutMs 3000, nothing is answered at 2999 ms, and the 504 comes at 3000 ms.
Use setTimeout and clearTimeout: the check moves them with fake timers, so a request's own timeout option or AbortSignal.timeout never fires there. A service that answers in time is not affected later: its timer must not fire once the answer has gone out.
- Task 5
createApp: answer 502 when a service is down
When the gateway cannot connect to a service (nothing listens on its port), or the service hangs up without answering, the gateway answers 502 with { error: 'Upstream unavailable', upstream: 'orders' }, naming the service, with its X-Request-Id ('gw-1' on a fresh app). The check waits at most 1.5 seconds.
The gateway itself must keep running: with the orders service down, the menu service still answers 200 through it.
What you will learn
- Forwarding: a mounted middleware that sends the request on with node:http and pipes the answer back, body untouched.
- Which headers cross: end-to-end headers go through; hop-by-hop headers stay behind, and Host names the service.
- Slow and down services: a timer for a 504, the error event for a 502, and answering only once.
More in Projects
Build "Project: the API gateway" 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.