Inside a back end

You choose two seats on a cinema's website, for Saturday at 20:30, and click "Book". Your browser sends a request to the cinema's back end, the part of the site that runs on its servers.

First, the request reaches a route: an address on the server for one kind of request. Here it's POST /bookings, which means "create a booking". The route receives the details: the film, the session, the seats and your account.

Then the rules decide. Are you logged in? Are these two seats still free? What's the price, according to the cinema's own price list? If a check fails, the request stops here, and the answer is a refusal.

Then the database saves the booking and marks the two seats as sold, so that nobody else can book them.

Last, the answer goes back to your browser: "Booked", with a booking number, or "Sorry, those seats were just sold". The page shows it.

Every back end works this way, from a cinema to a bank. The lesson Front and back shows which parts of a site run in the browser and which run on a server. Here we open the server's box. When you read a developer's plan or a bug report, ask what happens at each of the four steps.

A back end has a list of routes, one for each job it can do. Each route is a method and an address. The method says what kind of action it is: GET reads data, POST creates something, PUT or PATCH changes it, and DELETE removes it. The address is the part of a web address after the domain name, such as /bookings.

The example below shows the cinema's routes. Read it like a menu of what its back end can do. GET /films returns the films showing this week, and GET /films/42/sessions returns the times for film number 42. POST /bookings books seats, GET /bookings/1042 shows one booking, and DELETE /bookings/1042 cancels it.

A feature with no route doesn't exist on the server, however good the page looks. Developers also say "endpoint", which is another word for a route.

Each route is also a door. Anyone who knows its address can try it, even without the site or the app. So each route must check who is calling, and what they're allowed to do.

The rules are where the business lives. They're the company's decisions, written as code: what things cost, what's in stock, who can see what. "A booking can be cancelled up to two hours before the film, and is then refunded." "Students pay less on Wednesdays." Developers call these the business rules.

Each route has its own rules, and checks them before anything is saved. They run on the server, because the page can be changed by whoever uses it. The lesson Front and back explains why.

Many costly bugs live here. Sometimes nobody wrote a rule down, so the developer guessed it. Sometimes the same rule exists in two places, in the site and in the app, and the two versions disagree.

A good developer will ask you for these rules. Write them down in plain sentences, and include the odd cases: what happens to a booking for a film that's cancelled? Who gets the student price if the card has expired?

Every request gets an answer, and the answer says whether it worked. It starts with a status code: 201 when the booking was created, 409 when the seats were taken in the meantime, 401 when you're not logged in, 500 when the server itself failed. The lesson The request path explains how to read these codes.

A refusal or an error is an answer too, and it needs a clear message on the screen, just like success. "Sorry, those seats were just sold" helps. A blank page doesn't.

What comes with the status depends on the back end. Some back ends send a whole page, built on the server and ready to display. More and more often, the back end sends only data, in a format called JSON, and the page or the app builds what you see from it. The Front ends lessons show how a page is built in the browser.

The cinema has a website, an app, a film listings site that shows its times next to other cinemas', and a scanner that staff use at the door. All four ask the same back end. They do it through its API (application programming interface): the set of routes that other programs can call, which answer with data instead of a page. So there is one set of rules and one database, and every screen shows the same truth. Each program gets its own access, and only what it needs: the listings site can read the times, but it can't book or cancel anything.

The example below is a real request to a real API, run by the French state, which gives information about every commune in France. You can paste the address into your browser: https://geo.api.gouv.fr/communes?nom=Annecy&fields=population. On the left, the request: the method GET, the route /communes, then after the question mark the question itself: the commune called Annecy, and only its population. On the right, the answer: the status 200 OK, a header saying that the body is JSON, then the data. The square brackets hold a list, here of one commune. The curly braces hold one record, made of names and values: the population, the name ("nom"), the code that identifies each commune, and a score that says how well the name matched. One header says "X-Powered-By: Express": this API runs on Node.js, with the Express framework you'll meet in the next lesson.

You don't need to read the code to ask these questions.

Ask for the list of routes: it's the menu of what the back end does. For each route, ask who may call it: anyone, logged out or not, any customer, or only staff?

Ask for the rules each route checks, written in plain sentences, and where they live in the code: in one place, or in several that could disagree?

Ask about the answers that aren't a success. When a request is refused, not allowed or fails, what does the screen show? Ask to see it happen.

And ask who else will call the API: an app, a partner, a screen in a shop? If others will use it, it needs documentation, so that another team can use it without calling the developer.