Checking Input by Hand
An API can't trust what a request sends, so before it saves anything it checks each field for being there, having the right type, staying in its range and being an allowed value, and it collects every problem to send back at once.
Apprentice · FastAPI · Python · Updated
After this lesson you can
- Explain why an API checks every request body itself, even when a form or app already checks it
- Check a request body by hand for required fields, types, ranges and allowed values, collecting every problem instead of stopping at the first
Key takeaways
- Anyone can send any JSON to an API, so the API checks every request body itself, even when the app's form checked it first.
- A field can need four kinds of check, that it's there, that it's the right type, that it's in its range and that it's one of the allowed values.
- A type check comes before a range check, or comparing text with a number crashes the route.
- Collecting every problem in a list, instead of stopping at the first, lets the person fix them all in one go.
- Checks written by hand work, but they're long and every route needs its own, which is the job Pydantic takes over.
Every API that takes data in has to decide what to do when the data is wrong: a sign-up with no email, an order for minus three pizzas, a birthday in the year 3000. This lesson checks a request body by hand, one rule at a time, so you see every step that Pydantic does for you from the next lesson on.
The example is the Happy Tails Adoption Center. People apply to adopt a pet through its website: their name and email, their age, the pet's name and type, and whether their home has a yard.
The form isn't the only way in
The website's form won't send an application without an email, and its age box only takes numbers. That check runs in the browser, before anything is sent, and it's called client-side validation (the client is the program that sends the request). It's there to help people: they see a mistake before they press Send.
It doesn't protect the API. The API's address is public, so anything can send it a request: the docs page you've used since Module 1, a script, an old copy of the app, or someone trying to break it. Any of them can send this body:
{"name": "", "age": "fifteen", "pet_type": "dragon"}
So the API checks every request body itself, every time. That's server-side validation, and the rule behind it is often put as "never trust the client". The form's checks are for the person; the API's checks are for the data.
Four kinds of check
A field can need any of these:
| Check | The question it asks | In an application |
|---|---|---|
| Required | Was it sent, and is it more than blank? | email must be there |
| Type | Is it the right kind of value? | age must be a whole number, not "fifteen" |
| Range | Is it inside its limits? | age must be 18 or over |
| Allowed values | Is it one of the choices? | pet_type must be dog, cat or rabbit |
A first try checks the rules in order and returns the first problem it finds:
def first_problem(body):
if not body.get("email"):
return "email is required"
if body.get("age", 0) < 18:
return "age must be 18 or over"
return None
print(first_problem({"age": 15}))
print(first_problem({"email": "theo@example.com", "age": "fifteen"}))
email is required
Traceback (most recent call last):
TypeError: '<' not supported between instances of 'str' and 'int'
Two things go wrong. The first application has two problems, but the answer names one: the applicant fixes the email, sends it again, and only then hears about the age. And the second crashes, because Python can't compare the text "fifteen" with 18. Inside a route, that crash becomes a 500, a server error, for what is the sender's mistake.
Collecting every problem
The fix for both: check the type before the range, and keep going after a problem, adding each one to a list.
PET_TYPES = ["dog", "cat", "rabbit"]
def find_problems(body):
problems = []
if not body.get("email"):
problems.append("email is required")
age = body.get("age")
if not isinstance(age, int):
problems.append("age must be a whole number")
elif age < 18:
problems.append("age must be 18 or over")
if body.get("pet_type") not in PET_TYPES:
problems.append("pet_type must be dog, cat or rabbit")
return problems
print(find_problems({"email": "maya@example.com", "age": 34, "pet_type": "dog"}))
print(find_problems({"age": "fifteen", "pet_type": "dragon"}))
[]
['email is required', 'age must be a whole number', 'pet_type must be dog, cat or rabbit']
body.get("email") gives None when the field wasn't sent, and not treats None and the empty text "" alike, so one line catches both. isinstance(age, int) (read "is age an instance of int") asks whether the age is a whole number, and the elif compares it with 18 only when it is. not in checks the pet type against the allowed list. An empty list means the application is fine.
Using it in a route, and what it costs
A route runs the checks first and, when there are problems, raises a 422 with the whole list, as When It Isn't There: HTTPException and 404 raised a 404:
@app.post("/applications", status_code=201)
def apply(body: dict):
problems = find_problems(body)
if problems:
raise HTTPException(status_code=422, detail=problems)
saved = {"id": len(APPLICATIONS) + 1, **body}
APPLICATIONS.append(saved)
return saved
body: dict takes the request's JSON object as a plain dictionary, with nothing checked, so find_problems does all the checking. 422 Unprocessable Content means "your request arrived, but its data breaks the rules". Sent the body from the top of this lesson, the route answers 422 with every problem:
{"detail":["email is required","age must be a whole number","pet_type must be dog, cat or rabbit"]}
This works, and APIs were checked this way for years. But look at the cost: three fields took a dozen lines, the email check doesn't even look for an @, and every route that takes a body needs its own function. And the front end has to guess which box on the form each sentence belongs to. Keying each problem by its field, in a dictionary, would tell it.
Request Models with Pydantic replaces all of this with a class that names each field and its type.
Do it: check an adoption application
Before Happy Tails' staff read an application, the API checks it. The front end shows each problem beside its own box on the form, so it wants the problems keyed by field.
body: the application as a dictionary, as it arrived. It always has"age", a whole number."name"and"pet_type"may be missing.
Your job: write the function validate_application(body). It returns a dictionary with one entry for each field that has a problem: the field's name, and a sentence about it.
- When
nameis missing, or is only spaces or empty, add"name": "Please tell us your name.". - When
ageis under 18, add"age": "You must be 18 or over to adopt.". - When
pet_typeisn't"dog","cat"or"rabbit", add"pet_type": "We have dogs, cats and rabbits.". A missingpet_typecounts too. - Keep going after a problem: every problem goes in. A good application gives back an empty dictionary,
{}.
Worked through: validate_application({"name": " ", "age": 16, "pet_type": "dragon"}). The name is only spaces, 16 is under 18, and a dragon isn't one of the three, so it returns:
{"name": "Please tell us your name.", "age": "You must be 18 or over to adopt.", "pet_type": "We have dogs, cats and rabbits."}
Practiced live on the lesson page: write the Python right there and check it.
Check yourself
2 questions to try on the lesson page.
So what
An API is only as trustworthy as the data it lets in, and checking every field, every time, and saying everything that's wrong in one answer is what makes it trustworthy.