Path Parameters and Their Types
A path parameter such as {game_id} lets one FastAPI route answer every address of its shape, its type hint turns the text from the address into a number, FastAPI answers 422 when it can't, and a fixed path such as /games/today goes above the path parameter that would catch it.
Apprentice · FastAPI · REST API · Updated
After this lesson you can
- Read a value from the path with a path parameter, and give it a type hint that turns its text into a number
- Explain the 422 FastAPI sends when a path value has the wrong type, and put fixed paths above path parameters
Key takeaways
- A path parameter is a blank in a route's path, written in braces, such as /games/{game_id}. Whatever a request puts in that place arrives in the function's parameter of the same name.
- Everything in an address is text. The type hint int turns "2" into the number 2, so it can be compared with the numbers in your data.
- When the text can't be turned into the hinted type, such as abc for an int, FastAPI answers 422 and your function never runs.
- FastAPI tries routes in the order they're written, and the first match answers. A fixed path such as /games/today goes above /games/{game_id}.
Almost every app shows one thing out of many: order 1042, the profile of user 7, the page for one product. The app asks the API for that one thing by putting its id in the address, and the API reads the id back out. This lesson shows how a FastAPI route reads part of its address, and what happens when that part isn't what the route expected.
The example is the Rolling Dice board game café, whose staff app looks up the games on the café's shelf.
A route for every game?
The café's API already lists its shelf, as in Your First FastAPI App: GET /games answers with every game. Now the staff app needs one game at a time, at /games/1, /games/2 and so on. A first try is a route for each address:
@app.get("/games/1")
def get_game_1():
return GAMES[0]
@app.get("/games/2")
def get_game_2():
return GAMES[1]
It works for two games. The café buys new games every month, though, and every one would need another route. The routes are all the same except for one number.
Think of a form with a blank: Table number: ____. The form is printed once, and each guest fills in the blank. A path parameter is that blank in a route's path. It's written in braces: "/games/{game_id}", read "games slash game id in braces". Whatever a request puts in that place arrives in the function's parameter with the same name. Here is the café's whole main.py with one route for every game:
from fastapi import FastAPI
app = FastAPI()
GAMES = [
{"id": 1, "title": "Harbor Lights", "min_players": 2, "max_players": 4, "minutes": 45, "available": True},
{"id": 2, "title": "Moon Mice", "min_players": 3, "max_players": 6, "minutes": 20, "available": False},
{"id": 3, "title": "Tile Town", "min_players": 1, "max_players": 2, "minutes": 30, "available": True},
]
@app.get("/games")
def list_games():
return GAMES
@app.get("/games/{game_id}")
def get_game(game_id):
for game in GAMES:
if game["id"] == game_id:
return game
Run it with fastapi dev main.py and open http://127.0.0.1:8000/games/2 in your browser. The answer is 200 OK, with this body:
null
null is how JSON writes Python's None. The loop found no game, so the function ended without returning anything.
The type hint turns text into a number
Everything in an address is text. The request for /games/2 gives game_id the text "2", and the text "2" is never equal to the number 2 in the data, so no game matches.
The fix is a type hint, the note after a parameter's name that says what type it should be (Type Hints: Saying What a Value Should Be covers them). FastAPI reads the hint and turns the text into that type before your function runs:
@app.get("/games/{game_id}")
def get_game(game_id: int):
for game in GAMES:
if game["id"] == game_id:
return game
Save the file, and the server restarts with the change. /games/2 now answers with Moon Mice:
{"id":2,"title":"Moon Mice","min_players":3,"max_players":6,"minutes":20,"available":false}
An endpoint is a method and a path together, and this one, GET /games/{game_id}, covers every game: /games/1, /games/2, and every game the café buys next month, all answered by the one route. (An id that no game has, such as /games/9, still answers null; When It Isn't There: HTTPException and 404 fixes that.)
When the text isn't a number: 422
A typo in the app, or a person typing the address by hand, can send /games/abc. The text abc can't be turned into an int, so FastAPI doesn't call your function at all. It answers 422 Unprocessable Content: the request reached a real address, but a value in it breaks the rules. The body says where and why:
{"detail":[{"type":"int_parsing","loc":["path","game_id"],"msg":"Input should be a valid integer, unable to parse string as an integer","input":"abc"}]}
Read it from the inside out: loc (the location) is the path's game_id, msg says it should be a whole number, and input is what arrived. /games/2.5 gets the same 422, because 2.5 isn't a whole number either. Your function only ever sees a real int, so it never has to check.
The order of routes matters
The café also wants a game of the day, at /games/today. Here it's added below the route for one game:
@app.get("/games/{game_id}")
def get_game(game_id: int):
for game in GAMES:
if game["id"] == game_id:
return game
@app.get("/games/today")
def game_of_the_day():
return GAMES[0]
/games/today answers 422, with "input":"today". FastAPI tries the routes in the order they're written, and the first one whose path fits answers. /games/{game_id} fits /games/today, with today in the blank, and today isn't a number.
Move game_of_the_day above get_game:
@app.get("/games/today")
def game_of_the_day():
return GAMES[0]
@app.get("/games/{game_id}")
def get_game(game_id: int):
for game in GAMES:
if game["id"] == game_id:
return game
Now /games/today answers with Harbor Lights, and /games/2 still answers with Moon Mice. Fixed paths go first; the path parameter catches whatever is left.

Check yourself
2 questions to try on the lesson page.
So what
One route with a path parameter serves every item a resource will ever have, and its type hint means your function only ever sees the kind of value it can work with.