How your reading list works.

By the end of this part you’ll be able to explain what happens when you add a book to your reading list: which program asks, which one answers, and where the book is kept. You’ll also know how an app you sign in to, such as your email, does the same thing on a larger scale, and the one way yours differs.

You have a plan for what your app does and a brand pack for how it looks. Nothing is built in this part. You’ll watch the finished example at work, and Part 6 starts your own build.

1. Watch a request happen

Every browser has a set of developer tools that show what a page is doing behind the scenes. They are made for programmers and look busy. You need one tab of them.

1. Open the finished example in Chrome.
2. Open the developer tools: press F12 on Windows, or Option + Command + I on a Mac. A panel opens beside or below the page.
3. In that panel, choose the Network tab. It lists everything the page fetches. Near the top of the tab is a row of filters; choose Fetch/XHR, which hides the page’s own files and pictures. The list is probably empty now.
4. In the app, add a book. A new row named books appears in the list, with the number 201 beside it.
5. Click that row. More detail opens, arranged in tabs of its own. Look for the word POST and the number 201 near the top.
6. Choose Response. You’ll see your book written out as text, with its title, its status and an id that you never typed.

That row is one message from the page and one answer to it. The page sent your book to another program, and that program stored it, gave it an id and sent it back.

If no row appears, check that Fetch/XHR is chosen and that the developer tools were open before you added the book, then add another. If a note at the foot of the app says the server is running inside the page, your browser has hidden these messages, which some private windows do. Use an ordinary Chrome window.

2. Name what you saw

Client and server. You watched two programs talk. The client is the page itself: the list, the form and the buttons. It runs in your browser, and it is the one that asks. The server is a separate program that keeps the books and decides what is allowed. The two never reach into each other. The client cannot touch the stored books, and the server cannot touch your screen. All they can do is send each other messages.

Request and response. The message the client sends is a request. It has two main parts: a method, which is the kind of action wanted, and an address, which is the thing the action is about. POST is the method for “create something new”, and the address was api/books, so the row you clicked said “create a new book”. When the app opens, it sends GET api/books, which means “send me the list”. The server’s answer is a response. The text you read under Response was the book as the server stored it, written in JSON, a plain format of names and values that both programs can read.

Status code. Every response begins with a three-digit status code that says how it went. You’ll meet four of them in this series:

You don’t need to memorise them. You need to recognise them, because from Part 6 onwards you’ll watch them go by in your own app.

API. The agreed list of requests a server understands is called its API. It works like a contract between the two programs: it says which requests exist, what each must contain and what comes back. Your project’s API is written down in plain language in docs/api.md. It is one page, it was written for you as much as for your agent, and you don’t have to read it to carry on.

3. Follow one request there and back

Put those pieces in order and you have the whole of what happened when you added your book. Read this from top to bottom:

Notice step 3. The client adds the book to the screen only after the server has answered, so the screen never claims something the server didn’t do. If the server refuses or fails, the client says so and leaves the list as it was.

Notice step 2 as well, because the client had already checked. Try to add a book with no title in the finished example: the form stops you straight away, and no request is sent. That check is there because it is quicker and kinder for the person typing. The server checks again anyway, and would answer 400, because a server can never assume that every request comes from its own well-behaved client. The rules that matter live on the server.

4. Where the server usually lives

In the apps you use every day, those two programs run on different computers.

Think of your email. Your messages appear on whichever device you pick up, so they can’t be kept inside the page on any one of them. They are kept by a server running on a computer that belongs to the email company. That computer is switched on all the time, and everybody’s browser can reach it across the internet. Behind the server sits a database, a store built for holding a great deal of information and finding any of it quickly. You’ll hear this whole side of an app called the backend.

Everything a web app can do for a group of people follows from this arrangement. Because every browser talks to the same server, you and a friend can see the same information, and you can see yours from any device.

The work that a real server brings follows from this arrangement too. A server that everyone can reach has to know who is asking and what that person is allowed to see, which means accounts, passwords and careful security. Somebody also has to pay for the computer and look after other people’s information on it.

5. Where your server lives

Your reading list has the same two programs, sending the same kind of messages. The difference is where the server runs. It is a stand-in server: a small server program that runs inside your browser, next to the client, and not on someone else’s computer. It was the stand-in server that answered 201 when you added your book.

The stand-in server is already in your project, complete, in a folder called src/server. You won’t build it and you don’t need to open it. In Part 6 your agent builds the client that talks to it, exactly as it would build a client for a server across the internet.

Moving the server inside the browser means there are no accounts to set up and nothing to pay for. It also has a cost, and you should know it before you build. There is no single server that everyone’s browser reaches, so every browser runs its own stand-in server with its own books. When you publish your app and send a friend the link, they will see their own empty list, not yours. Books you add on your laptop will not appear on your phone. One shared list that you could both see is exactly what a real server would add.

Running the server inside the browser also leaves you very little to secure. With no accounts, and a server that lives in each visitor’s own browser, nothing a visitor types ever leaves their computer, so there is no login to break into and no shared store of other people’s information to protect. An app with accounts needs a great deal more, and Building RepGarden shows that work.

One more server is involved, and it is not in these pictures: the one that delivers the app’s files to your browser in the first place. We’ll call it the host. On your computer that job is done by the development server your agent starts, and Part 9 is where a public host takes over.

6. Where your books are kept

A real server keeps its information in a database. Your stand-in server has two places to keep the books, and you’ll use both.

It starts with its memory store. The books are held in the server’s memory and nowhere else. Refreshing the page restarts everything on it, including the stand-in server, so the list is gone. You’ll build the first half of your app this way in Part 6, and you’ll watch your books disappear on a refresh.

In Part 7 you switch the server to its saved store. It then also writes the list into localStorage, a small storage area that the browser gives to each website. The list now outlives the page that made it, which is called persistence. It is worth being exact about what that storage is:

• It lasts. The list survives refreshing, closing the browser and restarting the computer.
• It belongs to one browser on one device. Chrome on your laptop and Safari on your phone each keep their own list.
• It belongs to one website address. The app on your own computer and the app you publish keep separate lists.
• It is not a backup. Clearing the site’s data in your browser’s settings deletes the list, and nothing can bring it back.
• It is private. Nobody else receives your books, including whoever hosts the site.

A database on a real server does the same job with those limits removed: one copy, shared, reachable from anywhere and backed up.

7. Make the server slow, then make it fail

A server across the internet is sometimes slow and sometimes fails, and a good client copes with both. The stand-in server has switches that let you see both. You turn one on by adding a few characters to the end of the app’s address.

• Open the finished example with ?delay=1500 on the end of its address. Every response now takes a second and a half. You’ll see Opening your library… before the list appears, and the form’s button waits when you add a book.
• Now open it with ?fail=all. Every request fails with 500. The app says The server didn’t answer. and offers Try again, and it does not show an empty shelf as if you had no books. With the Network tab open you can see the 500 for yourself.

A note at the foot of the page tells you when a switch is on. Remove it from the address to return to normal; your books are untouched. You’ll use these switches on your own app in Part 7.

8. Ask your agent to show you

An agent can explain a project as well as change it. This prompt asks yours to describe your own project in the terms you’ve just learned, using the brief and the API description, and to change nothing. Open your project in your agent and paste:

Read docs/brief.md and docs/api.md. Do not change any files. In plain language, explain what the stand-in server in src/server does, and what the client will do once it is built. Then walk me through what will happen, step by step, when I add a book: which request is sent, what the server checks, and what comes back. Finally, explain what the development server does when I open the local address, and how that is different from the stand-in server. Keep it short, and define any technical term you use.

Compare the answer with the three pictures above. It should describe the same round trip, a server inside your browser, and a development server whose only job is to deliver the app’s files. If it uses a word you don’t know, ask what it means. If it contradicts something here, ask it to show you the line of docs/api.md it is relying on.

You can now explain how your app works, and how it differs from one with a real server. Next, in Part 6, your agent builds the client, and you watch your own app send its first request.

FAQ

Further reading

• What is an API? In English, please.freeCodeCamp

  A short, plain-language account of clients, servers and APIs, using booking a calendar event from another website as its example. It shows one block of JSON, and you can stop before the final section, which is about programming.

• How the web worksMDN

  A beginner’s explanation of clients, servers and what happens when you open an address, told through an analogy of a shop and a road.

• What is a web server?MDN

  Explains the difference between a server that only delivers files, like this app’s host, and one that also runs application code, which is the job our stand-in server does.