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

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 values
  • float: Floating-point values
  • str: String values (default)
  • bool: Boolean values
  • UUID: 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 values
  • float: Floating-point values
  • str: String values (default)
  • bool: Boolean values
  • list: 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.

How to pass parameters in FastAPI

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.

Categorized in:

Programming, Tutorials,

Last Update: 23/06/2024