# 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 November 19, 2026

By Gregor Dzierzon

## 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:

```python
@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:

```python
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:

```json
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:

```python
@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:

```json
{"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:

```json
{"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:

```python
@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`:

```python
@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.

![Two requests checked against the café's routes from top to bottom: GET /games/today stops at the first route, /games/today, and GET /games/2 passes it and stops at /games/{game_id} with game_id set to 2](https://fsdtrainingmedia.blob.core.windows.net/public/images/2026/11/27e0e29f604b4e349612a8a50b6ccb57.webp)

## 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.

## Key terms

- [Path Parameter](https://www.ask-codey.com/glossary/path-parameter)
- [Type Hints in FastAPI](https://www.ask-codey.com/glossary/type-hints-in-fastapi)
- [422 Unprocessable Content](https://www.ask-codey.com/glossary/422-unprocessable-content)
- [Endpoint](https://www.ask-codey.com/glossary/endpoint-rest-api)

## Related

- [Your First FastAPI App](https://www.ask-codey.com/lessons/fastapi-first-app)
- [Query Parameters: Filters and Options](https://www.ask-codey.com/lessons/fastapi-query-parameters)
- [When It Isn't There: HTTPException and 404](https://www.ask-codey.com/lessons/fastapi-not-found-httpexception)

Source: https://www.ask-codey.com/lessons/fastapi-path-parameters
