Checking Input by Hand

A server checks every request body before it saves anything, because any program can send anything, and a validation function collects every problem (a missing field, the wrong type, text that's too long, a value that isn't allowed) so the API can answer 400 with the whole list.

Apprentice · Node.js · REST API · Updated

By

After this lesson you can

  • Explain why a server checks every request body, even when the page that sends it already checks
  • Check a request body by hand for required fields, types, ranges and allowed values, collecting every problem

Key takeaways

  • Never trust a request body. A web page's own checks help the person typing, but REST Client, a script or an app with a bug can send anything, so the server checks again.
  • Four kinds of rules cover most fields. Required (is it there?), type (is it text?), range (is it 200 characters or fewer?) and allowed values (is it one of the four statuses?).
  • Collect every problem in a list instead of stopping at the first one, so the caller can fix them all in one try.
  • When the list isn't empty, answer 400 Bad Request with the list, and save nothing.

Every sign-up form, checkout page and booking app sends data to a server, and every one of those servers checks it before saving it. When a form answers "Email is required" after you press Send, that message often came from a check like the ones in this lesson, written on the server.

The POST /tickets route from Designing REST Endpoints: Create, Update and Delete saves whatever arrives. Two requests to Spoke & Chain's API, then each answer's status line and body:

POST /tickets  {}
HTTP/1.1 201 Created
{"id":4,"status":"waiting"}

POST /tickets  { "customer": 42, "bike": "", "problem": "flat tire", "status": "fixed?" }
HTTP/1.1 201 Created
{"id":5,"customer":42,"bike":"","problem":"flat tire","status":"waiting"}

Ticket 4 has no customer, no bike and no problem. Ticket 5's customer is a number, and its bike is blank. Both are on the shop's clipboard now, and every page that lists tickets has to cope with them.

Never trust a request body

Think of the shop's front desk. Before a bike goes on the repair rack, the clerk reads the intake form: a name, the bike, what's wrong. Checking data against your rules before you use it is called validation.

The shop's web page can check its own form, and it should: client-side validation tells the person typing about a mistake at once. But the server can't tell who sent a request. It might be the shop's page, REST Client, a script someone wrote, or a phone app with a bug, and only the page runs the page's checks. So the server checks every body itself, every time. Server-side validation is the one check nobody can skip.

Four kinds of rules

Most rules for a field are one of four kinds:

Kind The question A ticket's rule
Required Is it there? customer, bike and problem must be sent
Type Is it the right kind of value? customer is text, not 42
Range Is it within limits? problem is 200 characters or fewer
Allowed values Is it one of the choices? status is waiting, in repair, ready or picked up

Each kind is a test JavaScript already has. typeof (read "type of") gives a value's type as text, and trim() takes the spaces off both ends of a text, so a name made only of spaces counts as empty:

console.log(typeof "Lena");
console.log(typeof 42);
console.log(typeof undefined);
console.log("   ".trim() === "");
string
number
undefined
true

Collect every problem, not only the first

A clerk who hands the form back for the first mistake, then for the next, then the next, wastes three trips. A good clerk circles every mistake at once. A validation function does the same: it starts an empty list, adds a problem for each rule that fails, and gives back the whole list.

function checkText(body, field, problems) {
  const value = body[field];
  if (value === undefined) {
    problems.push({ field, message: `${field} is required.` });
  } else if (typeof value !== "string") {
    problems.push({ field, message: `${field} must be text.` });
  } else if (value.trim() === "") {
    problems.push({ field, message: `${field} can't be empty.` });
  }
}

function validateTicket(body) {
  const problems = [];
  checkText(body, "customer", problems);
  checkText(body, "bike", problems);
  return problems;
}

console.log(validateTicket({ customer: "Lena", bike: "folding bike" }));
console.log(validateTicket({ customer: 42, bike: "   " }));
console.log(validateTicket({}));
[]
[
  { field: 'customer', message: 'customer must be text.' },
  { field: 'bike', message: "bike can't be empty." }
]
[
  { field: 'customer', message: 'customer is required.' },
  { field: 'bike', message: 'bike is required.' }
]

checkText holds the three checks every required text field needs, so each field is one line in validateTicket. { field, message } is short for { field: field, message: message }. The else if chain means a field gets one problem at most: a missing customer is "required", not also "not text". Each problem names its field, so a web page can show the message beside the right box. An empty list means the body passed.

Ranges and allowed values

A length is a number to compare, and includes says whether a list holds a value, exactly as written:

const statuses = ["waiting", "in repair", "ready", "picked up"];

console.log("gears won't shift".length);
console.log(statuses.includes("ready"));
console.log(statuses.includes("fixed?"));
console.log(statuses.includes("Ready"));
17
true
false
false

Inside validateTicket, those become two more ifs. ! is read "not", so !statuses.includes(...) means "isn't one of the statuses". A ticket may leave status out, so it's only checked when it's there:

  if (typeof body.problem === "string" && body.problem.length > 200) {
    problems.push({ field: "problem", message: "problem must be 200 characters or fewer." });
  }
  if (body.status !== undefined && !statuses.includes(body.status)) {
    problems.push({ field: "status", message: "status must be one of: waiting, in repair, ready, picked up." });
  }

Answering 400 with the list

With all four rules in validateTicket (a checkText line for the problem, and the two ifs above), the route checks first and saves only a body that passes:

app.post("/tickets", (req, res) => {
  const problems = validateTicket(req.body ?? {});
  if (problems.length > 0) {
    res.status(400).json({ message: "The ticket isn't valid.", problems });
    return;
  }
  const ticket = {
    id: nextId,
    customer: req.body.customer.trim(),
    bike: req.body.bike.trim(),
    problem: req.body.problem.trim(),
    status: req.body.status ?? "waiting",
  };
  nextId = nextId + 1;
  tickets.push(ticket);
  res.status(201).json(ticket);
});

A request with no JSON body leaves req.body undefined in Express 5, and undefined.customer would crash the route. ?? (read "nullish coalescing") gives the value on its right when the one on its left is undefined or null, so the checks get {} and report every field as required. Ticket 5's request now gets:

POST /tickets  { "customer": 42, "bike": "", "problem": "flat tire", "status": "fixed?" }
HTTP/1.1 400 Bad Request
{"message":"The ticket isn't valid.","problems":[{"field":"customer","message":"customer must be text."},{"field":"bike","message":"bike can't be empty."},{"field":"status","message":"status must be one of: waiting, in repair, ready, picked up."}]}

400 means "I can't use what you sent", and the list says exactly why. Nothing was saved, so the clipboard stays clean.

Do it: check a repair ticket

The front desk wants the API to catch the three mistakes it sees most: a ticket with no customer, a problem left empty, and a status that isn't one of the shop's four.

Your job: write validateTicket(body), which returns a list of problems. Each problem is an object with a field and a message. The input:

  • body: the ticket that was sent, an object such as { customer: "Dana", bike: "blue cruiser", problem: "flat rear tire" }. Only customer, problem and status are checked; other fields, such as bike, are left alone.

The rules, checked in this order (customer, then problem, then status), with at most one problem for each field:

  • customer: if it's missing, add { field: "customer", message: "customer is required." }. If it's there but isn't text, add { field: "customer", message: "customer must be text." }. If it's text that's empty or only spaces, add { field: "customer", message: "customer can't be empty." }.
  • problem: the same three rules, with problem in place of customer: "problem is required.", "problem must be text." and "problem can't be empty.".
  • status: it may be left out. If it's there and isn't exactly "waiting", "in repair", "ready" or "picked up", add { field: "status", message: "status must be one of: waiting, in repair, ready, picked up." }.
  • When nothing is wrong, return an empty list, [].

Worked through: validateTicket({ customer: "Dana", problem: "", status: "fixed?" }). The customer is "Dana": there, text, not empty, so no problem. The problem is "": it's text, but empty, so { field: "problem", message: "problem can't be empty." }. The status "fixed?" isn't one of the four, so { field: "status", message: "status must be one of: waiting, in repair, ready, picked up." }. It returns those two problems, problem first, then status.

Practiced live on the lesson page: write the JavaScript right there and check it.

Check yourself

2 questions to try on the lesson page.

So what

A server that checks every body, and answers with every problem at once, keeps bad data off the clipboard and tells each caller exactly what to fix, whoever wrote the code that called it.

Key terms

Related