Path Parameters & Type Hints
Use dynamic routes with path parameters and automatic type validation.
Yesterday every endpoint had a fixed path like /health. What if I want URLs like /users/42 where the number changes?
That's a path parameter. You put a variable name in curly braces inside the path, and FastAPI extracts it for you:
@app.get("/users/{user_id}")
def get_user(user_id: int):
return {"user_id": user_id, "name": f"User {user_id}"}
When someone requests GET /users/42, FastAPI extracts 42, converts it to an int (because of the type hint), and passes it as user_id. If someone requests /users/abc, FastAPI returns a 422 error automatically — it knows abc isn't a valid integer.
So the type hint isn't just documentation — it actually validates the input?
Exactly. That's one of FastAPI's superpowers. The type hint user_id: int does three things:
- Validates — rejects non-integer values with a clear error
- Converts — turns the string from the URL into a Python
int - Documents — shows up in the auto-generated API docs
You can use str, int, float, or even bool:
@app.get("/items/{item_id}")
def get_item(item_id: int):
return {"item_id": item_id}
@app.get("/files/{file_path:path}")
def get_file(file_path: str):
return {"path": file_path}
The :path converter allows slashes in the parameter, so /files/data/reports/q1.csv captures data/reports/q1.csv.
Can I have multiple path parameters in one route?
Absolutely. Just add more variables:
@app.get("/courses/{course_id}/lessons/{lesson_id}")
def get_lesson(course_id: int, lesson_id: int):
return {
"course_id": course_id,
"lesson_id": lesson_id,
"title": f"Lesson {lesson_id} of Course {course_id}"
}
GET /courses/5/lessons/3 extracts course_id=5 and lesson_id=3. The parameter names in the path must match the function argument names exactly.
What happens if I define two routes that could match the same URL?
Order matters. FastAPI checks routes in the order you define them. If you have:
@app.get("/users/me")
def current_user():
return {"user": "current"}
@app.get("/users/{user_id}")
def get_user(user_id: int):
return {"user_id": user_id}
Put /users/me first. Otherwise /users/{user_id} would try to convert me to an integer and fail. Fixed paths always go before parameterized paths.
Practice your skills
Sign up to write and run code in this lesson.
Path Parameters & Type Hints
Use dynamic routes with path parameters and automatic type validation.
Yesterday every endpoint had a fixed path like /health. What if I want URLs like /users/42 where the number changes?
That's a path parameter. You put a variable name in curly braces inside the path, and FastAPI extracts it for you:
@app.get("/users/{user_id}")
def get_user(user_id: int):
return {"user_id": user_id, "name": f"User {user_id}"}
When someone requests GET /users/42, FastAPI extracts 42, converts it to an int (because of the type hint), and passes it as user_id. If someone requests /users/abc, FastAPI returns a 422 error automatically — it knows abc isn't a valid integer.
So the type hint isn't just documentation — it actually validates the input?
Exactly. That's one of FastAPI's superpowers. The type hint user_id: int does three things:
- Validates — rejects non-integer values with a clear error
- Converts — turns the string from the URL into a Python
int - Documents — shows up in the auto-generated API docs
You can use str, int, float, or even bool:
@app.get("/items/{item_id}")
def get_item(item_id: int):
return {"item_id": item_id}
@app.get("/files/{file_path:path}")
def get_file(file_path: str):
return {"path": file_path}
The :path converter allows slashes in the parameter, so /files/data/reports/q1.csv captures data/reports/q1.csv.
Can I have multiple path parameters in one route?
Absolutely. Just add more variables:
@app.get("/courses/{course_id}/lessons/{lesson_id}")
def get_lesson(course_id: int, lesson_id: int):
return {
"course_id": course_id,
"lesson_id": lesson_id,
"title": f"Lesson {lesson_id} of Course {course_id}"
}
GET /courses/5/lessons/3 extracts course_id=5 and lesson_id=3. The parameter names in the path must match the function argument names exactly.
What happens if I define two routes that could match the same URL?
Order matters. FastAPI checks routes in the order you define them. If you have:
@app.get("/users/me")
def current_user():
return {"user": "current"}
@app.get("/users/{user_id}")
def get_user(user_id: int):
return {"user_id": user_id}
Put /users/me first. Otherwise /users/{user_id} would try to convert me to an integer and fail. Fixed paths always go before parameterized paths.
Practice your skills
Sign up to write and run code in this lesson.