FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.6+ based on standard Python type hints. It is designed to be easy to use, fast to code, and suitable for production environments. One of the key features of FastAPI is its ability to handle parameters efficiently. In this article, we will explore various ways to pass parameters in FastAPI and provide detailed explanations and examples to help you understand and implement them effectively.

FastAPI parameters example
Path parameters
Path parameters are used to capture values from the URL path itself. They are typically used for passing unique identifiers or resource names. In FastAPI, you can define path parameters using curly braces {}
in the path declaration.
Defining path parameters
To define a path parameter, simply include it within curly braces in the path declaration. For example:
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(item_id: int):
return {"item_id": item_id}
In this example, item_id
is defined as a path parameter. FastAPI automatically extracts the value from the URL path and passes it to the read_item
function.
Path parameter types
FastAPI supports various types for path parameters. By default, path parameters are treated as strings. However, you can specify the type of the parameter using Python type hints. FastAPI will automatically convert the path parameter to the specified type. Some commonly used types include:
int
: Integer valuesfloat
: Floating-point valuesstr
: String values (default)bool
: Boolean valuesUUID
: Universally Unique Identifier (UUID) values
For example:
@app.get("/items/{item_id}")
async def read_item(item_id: int):
return {"item_id": item_id}
In this case, FastAPI will convert the item_id
parameter to an integer before passing it to the read_item
function.
Path parameters with predefined values
You can define path parameters with predefined values using Enum classes. This allows you to restrict the possible values for a path parameter. Here’s an example:
from enum import Enum
from fastapi import FastAPI
class ItemType(str, Enum):
ELECTRONICS = "electronics"
CLOTHING = "clothing"
BOOKS = "books"
app = FastAPI()
@app.get("/items/{item_type}")
async def read_item(item_type: ItemType):
return {"item_type": item_type}
In this example, the item_type
path parameter is restricted to the values defined in the ItemType
enum class. FastAPI will automatically validate the input and raise an error if an invalid value is provided.
Query parameters
Query parameters are used to pass additional data to an API endpoint. They are appended to the URL after a question mark ?
and are typically used for filtering, sorting, or pagination. In FastAPI, you can define query parameters as function parameters with default values.
Defining query parameters
To define a query parameter, simply include it as a function parameter with a default value. For example:
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/")
async def read_items(skip: int = 0, limit: int = 10):
return {"skip": skip, "limit": limit}
In this example, skip
and limit
are defined as query parameters with default values of 0
and 10
, respectively. FastAPI will automatically extract the values from the URL query string and pass them to the read_items
function.
Optional query parameters
By default, query parameters are considered optional. If a query parameter is not provided in the URL, FastAPI will use the default value specified in the function parameter. You can also make query parameters required by not providing a default value. For example:
@app.get("/items/")
async def read_items(required_param: str):
return {"required_param": required_param}
In this case, the required_param
query parameter is mandatory, and FastAPI will raise an error if it is not provided in the URL.
Query parameter types
Similar to path parameters, you can specify the type of query parameters using Python type hints. FastAPI will automatically convert the query parameter values to the specified type. Some commonly used types include:
int
: Integer valuesfloat
: Floating-point valuesstr
: String values (default)bool
: Boolean valueslist
: List of values
For example:
@app.get("/items/")
async def read_items(q: str = None, page: int = 1, size: int = 10):
return {"q": q, "page": page, "size": size}
In this example, q
is a string query parameter with a default value of None
, while page
and size
are integer query parameters with default values of 1
and 10
, respectively.
Multiple values for query parameters
FastAPI supports passing multiple values for a single query parameter. You can define a query parameter as a list type to accept multiple values. For example:
from typing import List
@app.get("/items/")
async def read_items(q: List[str] = None):
return {"q": q}
In this case, the q
query parameter can accept multiple values. FastAPI will parse the values as a list of strings.
Request body
In addition to path and query parameters, you can also pass data in the request body. This is commonly used for creating or updating resources. FastAPI uses Pydantic models to define the structure of the request body.
Defining request body
To define a request body, create a Pydantic model class that represents the expected structure of the data. For example:
from pydantic import BaseModel
class Item(BaseModel):
name: str
description: str = None
price: float
tax: float = None
@app.post("/items/")
async def create_item(item: Item):
return item
In this example, the Item
model defines the structure of the request body. FastAPI will automatically parse the JSON request body and validate it against the model.
Nested models
You can also define nested models to represent complex data structures. For example:
from pydantic import BaseModel
class ItemDetails(BaseModel):
description: str
price: float
tax: float = None
class Item(BaseModel):
name: str
details: ItemDetails
@app.post("/items/")
async def create_item(item: Item):
return item
In this case, the Item
model contains a nested ItemDetails
model. FastAPI will automatically parse the nested structure and validate it accordingly.
Request files
FastAPI also supports handling file uploads using the File
and UploadFile
classes from the fastapi
module.
Uploading a single file
To handle a single file upload, use the File
class as a function parameter. For example:
from fastapi import File
@app.post("/upload/")
async def upload_file(file: bytes = File(...)):
return {"file_size": len(file)}
In this example, the file
parameter is defined as a bytes
type with a File
class as the default value. The ...
(ellipsis) indicates that the file is required. FastAPI will read the uploaded file and pass its contents as bytes to the upload_file
function.
Uploading multiple files
To handle multiple file uploads, use the List
type with the File
class. For example:
from fastapi import File
from typing import List
@app.post("/upload-multiple/")
async def upload_multiple_files(files: List[bytes] = File(...)):
return {"file_sizes": [len(file) for file in files]}
In this case, the files
parameter is defined as a list of bytes
with the File
class. FastAPI will accept multiple files and pass them as a list of bytes to the upload_multiple_files
function.
Advanced file handling
For more advanced file handling, such as retrieving file metadata or using file-like objects, you can use the UploadFile
class instead of File
. The UploadFile
class provides additional functionality, such as accessing the file name, content type, and a file-like object for reading the file contents.
from fastapi import UploadFile
@app.post("/upload/")
async def upload_file(file: UploadFile = File(...)):
return {"filename": file.filename, "content_type": file.content_type}
In this example, the file
parameter is defined as an UploadFile
instance. FastAPI will provide additional file metadata, such as the file name and content type, through the UploadFile
instance.
Form data
FastAPI also supports handling form data using the Form
class from the fastapi
module. This is useful when you need to receive data submitted via HTML forms.
Defining form parameters
To define form parameters, use the Form
class as a function parameter. For example:
from fastapi import Form
@app.post("/login/")
async def login(username: str = Form(...), password: str = Form(...)):
return {"username": username}
In this example, the username
and password
parameters are defined as form parameters using the Form
class. FastAPI will extract the values from the submitted form data and pass them to the login
function.
Combining form data and files
You can combine form data and file uploads in a single request using the File
and Form
classes together. For example:
from fastapi import File, Form
@app.post("/submit/")
async def submit_form(
name: str = Form(...),
email: str = Form(...),
file: UploadFile = File(...)
):
return {"name": name, "email": email, "file": file.filename}
In this case, the name
and email
parameters are defined as form parameters, while the file
parameter is defined as a file upload. FastAPI will handle both form data and file uploads in a single request.
Conclusion
FastAPI provides a powerful and flexible way to handle parameters in your API endpoints. Whether you need to capture values from the URL path, extract query parameters, receive request bodies, handle file uploads, or process form data, FastAPI has you covered.
By leveraging FastAPI’s intuitive syntax and Pydantic models, you can define and validate parameters easily. FastAPI’s automatic type conversion and validation ensure that you receive the expected data types and catch any invalid inputs early in the request processing pipeline.
With the knowledge gained from this article, you should now feel confident in defining and handling various types of parameters in your FastAPI applications. Remember to choose the appropriate parameter type based on your specific requirements and use cases.
FastAPI’s extensive documentation and vibrant community provide further resources and examples to help you dive deeper into advanced parameter handling techniques and best practices.