The round trip that fetches data

A request is always made of the same four parts.

• The path … who this is addressed to. A string like /api/posts
• The method … what you want done to it. GET, POST and so on
• The headers … the extra details. Your ID, what format the contents are in, what format you would like back
• The body … the contents you are sending over. Often empty on a request that only fetches

Think of an address (the path), what you want (the method), a delivery note (the headers) and the parcel (the body) and you are close.

The important bit is that the same path with a different method is a different request. /api/posts with GET means "give me the list", with POST it means "add one". So when you point at a round trip, name the method along with the path.

Five methods are enough to be getting on with.

• GET … fetch. Does not change anything on the server
• POST … send over. Often used for making something new
• PUT … replace the whole thing
• PATCH … change only part of it
• DELETE … remove it

The single most important thing here is that you must not change anything with GET. There are two reasons.

One is that it gets carried out just by being opened again. A GET gets sent again when you go back through history, gets prefetched by the browser, gets walked over by a search crawler. That is how "it vanished just because I opened it" happens.

The other is that it gets saved along the way (cached). A GET is assumed to give the same result however many times you send it, so it gets remembered all over the place. Put something that changes state in there and it will sometimes be carried out and sometimes not.

The format most used on the data round trip is JSON. It carries only values; no colours, no sizes.

• A key and a value are paired with :, and pairs are lined up with ,
• A value can be a number, a string, a true or false, an array, or a nested set of pairs
• Strings always go in double quotes (single quotes are not allowed)

Which format you sent is announced in the Content-Type header. You would think looking at the contents would tell you, but it is written on the outside so the receiving side can settle how to read it first.

Because it carries no appearance, one and the same response can build a web screen or a phone app screen. How it gets laid out is up to the side that received it.

Between the request arriving and the response going out, the inside of the server roughly goes in this order.

• ① Routing … deciding which piece of handling this path and method go to
• ② Authentication … checking who the request is from (looking at the ID)
• ③ Authorization … deciding whether this person is allowed to do this
• ④ Validation … looking at whether the contents sent make sense (is the quantity 1 or more, and so on)
• ⑤ The actual work … doing the thing you actually wanted done
• ⑥ The database and outside services … reading, writing, or going out to ask someone else
• ⑦ Shaping the reply … putting together the data and the number to return

The part to remember is the order. You do not do the actual work before you have checked. No writing things away before you know who this is, no touching the database before you have looked at whether the contents make sense.

② and ③ are different things. ② is "who are you", ③ is "is this person allowed to do that". And ② comes first, because you cannot decide whether to allow it while you still do not know who it is.

When you use an outside service for weather or maps or payments, the one that goes and calls it is the server, not the browser.

The reason is the one from the first lesson. Everything you send to the browser is visible, so handing a secret key to the device is the same as publishing it.

So the round trip comes in two hops. The browser calls your own server without holding a key. Your own server attaches the key and calls the outside service. Then it picks out only what is needed from what came back and passes that to the browser.

There is a bonus, too. The awkward parts of the outside service (limits on how often you may call, changes to the shape it returns) get shut inside your own server. If the other side changes its terms, there is one place to fix.

Every response comes with a three-digit number (a status code). The hundreds digit does the big splitting up.

• 2xx … it worked
• 3xx … please go somewhere else
• 4xx … a problem with how you asked (there is something to fix on the request side)
• 5xx … a problem on the server side (the handling fell over at the receiving end)

Let us look at just the common 4xx ones.

• 400 … the contents sent do not make sense
• 401 … it cannot tell who the request is from (no ID, or an expired one)
• 403 … it knows who you are, but this is not allowed for you
• 404 … there is nothing at that address

The difference between 401 and 403 is whether it stopped at ② authentication or at ③ authorization. With 401 there is a chance of getting through by presenting an ID; with 403 presenting it again will not help.

The part that pays off most in practice: 4xx and 5xx are fixed by different people. 4xx is about the sending side fixing what it sends; 5xx is about the people who built the server fixing the inside.

The mix-up to watch for here is that "failed" and "nothing found" are different things.

A request for a list comes back 200, and the contents are an empty array. That is a success. The server did go and look, and answered correctly: there was nothing matching.

• Failed … the number is 4xx or 5xx. No answer could be produced
• Nothing found … the number is 2xx. An answer was produced, and nothing matched

Treat these two the same on screen and you end up printing "the connection failed" where you should be saying "no posts yet". To the person using it, that looks broken.

The order for deciding is the number first, the contents second. Once the number tells you it succeeded, then you look at whether the contents are empty.

When you turn the result of a round trip into a screen, there are four states to draw.

• Loading … nothing has come back yet
• Succeeded with contents … show the list or the detail
• Succeeded but nothing found … say "there is nothing here yet"
• Failed … say what happened, and what to do next

Unless you draw all four, the screen looks broken. Do not draw loading and it stays blank until something comes back. Do not draw the empty case and the gap is just left there. Do not draw failure and it looks stuck on loading forever.

When building, write loading and failure first. Write only the case where it went well and try to add the rest later, and the rest usually gets forgotten.

Send a data round trip to a different domain and the browser sometimes refuses to hand you the response. That is the mechanism called CORS.

The first thing to take on board is that this is a safety catch on the browser side. It does not mean your server is weak, and it does not mean you are being attacked.

What it is protecting is the permissions you hold on some other site you have open, from being used without your say-so. The browser sometimes attaches your ID automatically, so being able to make round trips freely from any page at all would be a problem.

Which is why permission is given on the server side. Write into the response headers that "coming from this domain, you may hand it over" and the browser allows it through. You cannot switch it off from JavaScript in the browser.

And it does not happen between servers. The one running this mechanism is the browser, so a round trip with no browser involved has nobody to stop it.

When a data round trip fails, the order you follow is always the same.

Look at the number first. That alone settles half of where to search.

• 4xx … look at what you sent. Path, method, headers, body. Did you forget to attach the ID, is the shape of the contents right
• 5xx … look at the server. No amount of fiddling with what you sent will fix it. The server logs have the place it fell over
• No number at all … it never arrived. That is an address question, a connection question, or a CORS question

The tool to look with is the network panel in the browser developer tools. It shows you both what was sent and what came back. Look at only one of them and guess, and you will usually miss.

The short way out of your own assumptions is to check whether what you think you sent really did get sent. A header you were sure you attached not being in there is a very common story.

We have followed one data round trip, split into three.

• The sending side … four parts: path, method, headers, body. GET only fetches and changes nothing
• Inside the server … routing → authentication → authorization → validation → the actual work → the database → shaping the reply. No work before the checks
• After it comes back … 4xx is a problem with how you asked, 5xx is a problem on the server side, and they are fixed by different people. 401 means it cannot tell who you are, 403 means it knows and this is not allowed
• The screen … draw all four of loading, contents, nothing found, failed. Nothing found is not a failure

CORS is a safety catch on the browser side, and permission comes from the server. It does not happen between servers.

That is the end of this chapter. Being able to settle which part you are talking about is enough. When you do start getting your hands on it, the names of the tools will land on top of this map.