In the previous lesson we left a project with empty folders, installed dependencies and validated configuration, but unable to answer anything at all. Today that changes: by the end you will have an Express server listening on http://localhost:3000 that serves GET /v1/coffees and GET /v1/coffees/cof_001 with the exact format we settled on in module 2, a health endpoint, and a 404 that already speaks the language of the contract. Along the way we will understand the one idea you really must understand in order to work with Express —middleware—, we will see why separating app.js from server.js is an architectural decision and not a whim, and we will mount the Router under /v1, which is where the path versioning decided in 02-07 stops being a diagram and becomes code.

1. What Express is and what it is not
2. The central concept: middleware
3. The life cycle of a request
4. src/app.js and src/server.js: why they are separate
5. First start-up and the health endpoint
6. Built-in middleware: express.json and express.urlencoded
7. Express's Router and mounting /v1
8. In-memory data: src/repositories/coffees-memory.js
9. The first coffee routes
10. Routes with parameters and req.params
11. Sending responses: res.status, res.json, res.set, res.sendStatus
12. The generic 404 with the contract's error format
13. Testing it all with curl
14. Request logging: morgan and how far we go today

Node includes an http module with which you can already put together a server:

It works, and it teaches something important: Express does nothing you could not do yourself. But that if/else grows unmanageable the moment there are twenty routes, path parameters, JSON bodies to parse and behaviour common to every request.

Express is a thin layer over node:http that contributes exactly four things:

And it is just as important to know what it is not: Express is not a "batteries included" framework. It brings no ORM, no validation, no authentication, no mandatory folder structure. All of that is on you —which is why this module has eight lessons. In exchange, there is no magic: everything that happens during a request is written in one of your own files. For learning how an API really works it is the best possible choice. In 05-03 we will compare Express with Fastify, NestJS and others.

A middleware is a function that receives the request, may do something with it and decides whether to pass it on to the next function in the chain. Its entire definition fits into one signature:

And three rules that explain 90% of a beginner's problems with Express:

1. Middleware run in the order in which they are registered. There are no priorities and no magic: it is a list, from top to bottom.
2. If a middleware neither calls next() nor responds, the request hangs until the client gives up. It is the most frequent mistake.
3. If a middleware responds (res.json(...)), the chain ends there. Calling next() afterwards causes the notorious ERR_HTTP_HEADERS_SENT.

An example with three chained middleware, to see the ordering live:

A route handler (app.get, app.post) is also a middleware; it is simply conditioned on a method and a path. That uniformity is the key to Express's design: everything is the same thing. The validation of 03-04, the authentication of 03-06 and the error handling of 03-07 will all be middleware with this very signature.

This is the complete journey a request will take through Aroma Store by the end of the module. Today we build the grey boxes; the rest arrive in the lessons indicated.

What you have to retain: a request travels down the chain from top to bottom and leaves through one of two exits, a normal response or the error middleware. Nothing else.

Almost every Express tutorial puts the creation of the app and the call to listen() in a single file. We do not, and the reason is concrete:

The payoff shows up in 03-08. Supertest, the tool we will use to test the API, accepts Express's app object and fires requests at it without opening any TCP port. If app.js called listen(), every test file would occupy port 3000 and two suites running in parallel would clash with EADDRINUSE. By separating them, the app is a reusable object and the port is a deployment detail.

We start with src/app.js:

And src/server.js:

About the graceful shutdown: without it, Ctrl+C cuts everything off abruptly and a half-answered request dies with no response. With server.close(), the socket stops accepting new clients but the live requests finish. In 03-05 we will add the database shutdown here, and in 03-07 the capture of the process's unhandled errors.

Notice the direction of the imports: server.js imports app.js, never the other way round.

In another terminal:

Three details of that response are worth pausing on:

• Content-Type: application/json; charset=utf-8 was set automatically by res.json(). It is what we declared in the contract.
• ETag also comes as standard. It is the basis of conditional caching, which we cover in 04-06.
• There is no X-Powered-By, thanks to app.disable.

Why is /health outside /v1? Because it is not part of the public API: it is not consumed by the SPA or Aroma Mobile, but by the load balancer and the monitoring system. It is not part of the versioned contract, so it must not be versioned. It is the exception that proves the rule of 02-07.

When a POST arrives with a JSON body, the body travels as a stream of bytes. Without help, req.body is undefined. express.json() is a middleware that reads that stream, parses it and leaves the object in req.body.

Add it to src/app.js, before the routes:

Two consequences you should know about right away. The first: if the client sends malformed JSON, express.json() throws a SyntaxError which today produces an ugly HTML error page; in 03-07 we will turn it into a 400 invalid_data from the contract. The second: if the client does not send Content-Type: application/json, the middleware parses nothing and req.body stays as {}; it is the number one cause of "my POST arrives empty".

Putting every route in app.js works with two of them and is untenable with twenty-four. A Router is a mini Express application: it has its own routes and its own middleware, and it is mounted under a prefix.

We are going to create two files. First, the coffee router (src/routes/coffees.js), which for now only declares its relative routes:

And now the aggregator (src/routes/index.js), which brings together all the version 1 routers:

And it is mounted in src/app.js:

The result is a composition of prefixes across three levels:

And here is the real payoff of 02-07 turned into code: the day a v2 exists, you create src/routes/v2/ and add app.use('/v2', v2Routes). The two versions coexist in the same process, sharing services where the behaviour does not change and diverging where it does. Without this mounting, "coexisting versions" would be a nice phrase that is impossible to implement.

We do not have a database yet —that is 03-05— so the coffees will live in an array. But we already place it in the repositories folder and behind an interface, because the stated goal is to replace it with SQLite without the rest of the code noticing.

Two decisions that look minor and are not:

• The method names (findAll, findById) are the repository's interface. In 03-05 we will write coffees-sqlite.js with exactly the same names, and switching from one to the other will mean changing one import.
• Copies are returned ({ ...coffee }), not the array's references. If we returned the reference, any layer above could modify the "store" by accident. With a real database this is impossible by construction; in memory it has to be enforced by hand.

Now we connect the repository to the router. Replace the contents of src/routes/coffees.js:

Important details in this file:

• The envelope only appears on the collection. GET /v1/coffees returns {data, total}; GET /v1/coffees/:id returns the bare object. It is exactly what we decided in 02-05.
• return res.status(404)...: the return gives nothing useful back to Express, but it stops the function from running on. Without it, execution would carry on to res.status(200) and cause ERR_HTTP_HEADERS_SENT.
• total is today the length of the array. When 03-03 brings filters and pagination, total will be the number of items that match the filter, not the number returned in the page. That distinction costs bugs.
• ?? null (nullish coalescing) returns the left-hand value unless it is null or undefined. Do not confuse it with ||, which would also replace 0 or the empty string.

'/:id' declares a variable segment. Express captures whatever sits in that position and leaves it in req.params.id, always as a string.

The fact that our identifiers are prefixed strings (cof_001) plays in our favour: there is nothing to convert and no need to worry about a parseInt returning NaN. It was a decision made in 02-02 and here it pays its first dividend.

A warning about ordering, which is the classic trap:

Express walks the routes in declaration order and keeps the first one that matches. The concrete goes before the variable.

A very useful sibling is router.param(), which runs code every time a particular parameter appears —for example, loading the coffee and leaving it in req.coffee. We mention it so you know it exists; in this course we prefer to do it explicitly in the service.

Three practical warnings:

In this module we will almost always use the same pattern: res.set(...) for the contract's headers and res.status(...).json(...) for the body.

If you request GET /v1/nonexistent, no route matches and Express answers with its default 404: an HTML page with the text Cannot GET /v1/nonexistent. For a consumer expecting JSON, that breaks the contract on three fronts: the wrong Content-Type, an unknown body shape and a leak of the framework.

We add a final middleware in src/app.js, after all the routes:

Two clarifications about the catalogue. The code route_not_found was not in the catalogue of 02-04, which only had the specific 404s (coffee_not_found, order_not_found…). We are adding it now for the generic case —a URI that does not exist at all— and that is perfectly legitimate: the rule we set is that the catalogue only grows; adding a code is an additive change, withdrawing one would be breaking. And it must be documented in openapi.yaml, because an undocumented error code is not part of the contract.

The difference between the two 404s is worth being clear about:

The order is critical. This middleware must be registered last among the normal ones; if it came before app.use('/v1', v1Routes), it would answer 404 to absolutely everything. In 03-07 we will add the error middleware behind it, which is the only one that goes afterwards.

The complete src/app.js ends up like this:

Those five numbered blocks are the application's definitive ordering. Throughout the rest of the module we will only insert pieces between them; we will never change the sequence.

With npm run dev running, in another terminal:

If you have jq installed, it reads much better:

Note the 14.5. The contract of 02-05 says "euros with two decimals", but JSON does not distinguish 14.50 from 14.5: they are the same number and that is how JSON.stringify serialises it. Two decimals are a matter of presentation format, the client's responsibility, not the transport's. What matters —and what we do control— is that the value is exact, and it is, because underneath it is 1450 whole cents. If a consumer literally needed the string "14.50", the price would have to be serialised as text, and that is a contract decision we already ruled out in 02-05.

Five checks, five responses that conform to the contract. In 03-08 we will turn exactly these calls into automated tests with Supertest, so that nobody ever has to run them by hand again.

Right now the terminal says nothing when a request arrives, and that makes debugging uncomfortable. The minimal solution is a five-line middleware, which doubles as a perfect example of the signature we have learned:

The usual alternative is morgan (npm install morgan), a logging middleware with predefined formats:

Either will do for development. But let us be clear that this is not observability: there are no log levels, no structured JSON format, no correlation identifier, no metrics and no traces. console.log in production is a log nobody can query or aggregate. Serious observability —structured logs with pino, metrics, distributed traces and the traceId we will emit on 500s— is lesson 04-07. In 03-07 we will take the first step by generating that traceId to correlate an error with its log.

1. The request hangs forever. A middleware neither called next() nor responded. Walk the chain from top to bottom looking for the one that closes no path.

2. Error: Can't set headers after they are sent. You responded twice: a res.json() without return followed by another one, or a next() after responding. Always use return res.json(...) when the function could carry on.

3. Routes return 404 even though the file exists. It is almost always the mounting: remember that a router's routes are relative. If you write coffeeRoutes.get('/coffees', ...) and mount it at /v1/coffees, the real URL is /v1/coffees/coffees.

4. req.body is undefined. express.json() is missing, or it is registered after the routes. Order rules.

5. req.body arrives empty even though express.json() is in place. The client did not send Content-Type: application/json. In curl, the option is -H "Content-Type: application/json".

6. /:id declared before a fixed route. /featured stops existing. The specific comes first.

7. EADDRINUSE: address already in use :::3000. Another process holds the port, usually an earlier npm run dev that did not die. lsof -i :3000 identifies it; kill <pid> closes it.

8. Putting business logic inside the route. Today we queried the repository directly from the router because there is nothing else. It is the last time: in 03-03 it is split into controller and service, and it will not happen again.

Tip: define the middleware ordering once, comment it with numbers as we have done in app.js, and respect it. The hardest failures to diagnose in Express are always ordering failures.

Add to the coffee router the route GET /v1/coffees/:id/reviews, which is part of the URI map of 02-02. There are no reviews yet, so it must return an empty collection with the contract's envelope, but only if the coffee exists; if it does not, it must return 404 coffee_not_found. Explain why an empty collection is 200 and not 404.

Write a middleware called serverHeader that adds the header Aroma-Version: 1.0.0 to every response. Register it in src/app.js in the right position and justify that position. Check the result with curl -i. Why Aroma- and not X-Aroma-?

This code has three errors. Find them, explain what happens to the request in each case and write the corrected version.

Solution 1

Why 200 and not 404: the requested resource is the collection of reviews of coffee cof_001, and that collection exists; it simply happens to be empty. A 404 would mean "this URI identifies no resource", and it would force the client to treat the perfectly normal case of "no reviews yet" as an error. The rule, which we already saw in 02-04: an empty collection is 200 with {"data": [], "total": 0}; a nonexistent resource is 404. Consistent with the decision of 02-05 that empty arrays are represented as [] and never as null or omitted.

Solution 2

Why that position: it must go before anything that could respond —routes, the 404, errors— because headers can only be set while the response has not yet been sent. Placed first, the header accompanies every response, including the 404s and the 500s.

Why Aroma- and not X-Aroma-: the X- prefix for non-standard headers was deprecated by RFC 6648 in 2012. The historical problem is that many X- headers ended up being standardised and then two names coexisted for the same thing (X-Forwarded-For is the canonical example). The current recommendation is to use your own vendor prefix without X-, which is why the contract of 02-05 settled on Aroma-.

Solution 3

Corrected version:

A note on next: it has been removed from the signature altogether. A final route handler does not need next because it always responds; declaring it invites calling it by mistake. In this module we will only use it in intermediate middleware and, from 03-07 onwards, to propagate errors with next(error).

There is a server now. And beyond the fact that it responds, what matters is what you have understood about it: that Express is an ordered chain of middleware with the (req, res, next) signature, that each piece decides whether to hand over the turn or respond, and that the registration order is the execution order, without exceptions. That idea is 90% of Express, and with it the validation of 03-04, the authentication of 03-06 and the error handling of 03-07 will slot in without surprises.

You have also taken three structural decisions that hold up the rest of the module. app.js separated from server.js, so that the application is an object the tests of 03-08 can use without opening a port. The Router mounted at /v1, which turns the path versioning of 02-07 into a three-level composed prefix and makes a future v2 a line of code rather than a migration. And the store behind a repository interface with findAll and findById, whose names will reappear identically in 03-05 when SQLite sits behind them. On top of that, the responses already comply with the contract: the {data, total} envelope on the collection, the bare object on the item, cents on the inside and euros on the outside, and a 404 with code, message and details.

What grates today is that all the logic lives inside the router, that the conversion to the public representation is a loose function with a "provisional" comment, and that we only know how to read. In 03-03, Handling Requests and Responses, we fix that: we will squeeze the req and res objects, split the code into routes → controllers → services, write the representation mapper where it belongs, and implement the complete write contract —POST with 201 and Location, PUT, PATCH with merge-patch+json and its 415, soft DELETE— along with the filtering, sorting, pagination and the Link header we designed in 02-06.