FastAPI Route Handling: Leveraging Path and Query Parameters
Table of Contents
Fundamental Concepts
Path Parameters
Path parameters are part of the URL path itself. They are used to specify a specific resource or a group of resources. For example, in a URL like /users/123, 123 is a path parameter that might represent the ID of a user. FastAPI allows you to define path parameters in your route decorators using curly braces {}.
Query Parameters
Query parameters are used to pass additional information to the API endpoint. They are appended to the end of the URL after a question mark ? and are separated by ampersands &. For example, in a URL like /users?limit=10&offset=0, limit and offset are query parameters. Query parameters are often used for filtering, pagination, and sorting.
Usage Methods
Path Parameters
Here is a simple example of using path parameters in FastAPI:
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
def read_item(item_id: int):
return {"item_id": item_id}
In this example, we define a route /items/{item_id} where {item_id} is a path parameter. The function read_item takes an argument item_id of type int. FastAPI will automatically convert the path parameter from a string to an integer.
Query Parameters
Here is an example of using query parameters in FastAPI:
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/")
def read_items(skip: int = 0, limit: int = 10):
return {"skip": skip, "limit": limit}
In this example, we define a route /items/ that accepts two query parameters skip and limit. The function read_items takes two arguments skip and limit with default values of 0 and 10 respectively. If the user does not provide these query parameters in the URL, the default values will be used.
Common Practices
Using Type Hints
FastAPI uses Python type hints to validate and convert the incoming data. Always use type hints for your path and query parameters to ensure that the data is in the correct format.
Optional Query Parameters
You can make query parameters optional by using the Optional type from the typing module. Here is an example:
from fastapi import FastAPI
from typing import Optional
app = FastAPI()
@app.get("/items/")
def read_items(q: Optional[str] = None):
if q:
return {"query": q}
return {"message": "No query provided"}
Multiple Path and Query Parameters
You can use multiple path and query parameters in a single route. Here is an example:
from fastapi import FastAPI
app = FastAPI()
@app.get("/users/{user_id}/items/{item_id}")
def read_user_item(user_id: int, item_id: int, q: Optional[str] = None, short: bool = False):
item = {"item_id": item_id, "owner_id": user_id}
if q:
item.update({"q": q})
if not short:
item.update(
{"description": "This is an amazing item that has a long description"}
)
return item
Best Practices
Error Handling
When using path and query parameters, it’s important to handle errors gracefully. FastAPI will automatically raise a 422 Unprocessable Entity error if the incoming data does not match the expected type. You can use custom exception handlers to provide more user-friendly error messages.
Documentation
FastAPI automatically generates interactive API documentation using Swagger UI and ReDoc. Make sure to add descriptions and examples to your path and query parameters using the description and example arguments in the Query and Path classes.
from fastapi import FastAPI, Query, Path
app = FastAPI()
@app.get("/items/{item_id}")
def read_item(
item_id: int = Path(..., title="The ID of the item to get", ge=1),
q: str = Query(None, title="Query string", min_length=3, max_length=50),
):
results = {"item_id": item_id}
if q:
results.update({"q": q})
return results
Security
Be careful when using user-provided path and query parameters, especially if they are used in database queries or other sensitive operations. Always validate and sanitize the input to prevent SQL injection and other security vulnerabilities.
Conclusion
FastAPI’s route handling capabilities, especially when it comes to path and query parameters, provide a powerful and flexible way to build dynamic APIs. By understanding the fundamental concepts, usage methods, common practices, and best practices, you can create robust and secure APIs that meet the needs of your application. Whether you are building a small internal API or a large-scale production API, FastAPI’s path and query parameters can help you achieve your goals efficiently.