Accessing lists as query param in FastAPI

FastAPI is a powerful web framework for building APIs with Python. One of the key features of FastAPI is its support for query parameters, which can be used to parameterise the behaviour of API responses. In this blog post, we will explore how to access lists as query parameters in FastAPI.

Query Parameters in FastAPI

Query parameters are key-value pairs that are added to the end of a URL after a question mark. For example, consider the following URL:

https://localhost:8000/items?page=1&limit=10

In this URL, page, and limit are query parameters that are passed to the API. Query parameters are optional and can be used to filter, and paginate API responses.

To define query parameters in FastAPI, we can use the Query function from the fastapi module. Here's an example:

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items")
async def read_items(page: int = Query(1, gt=0), limit: int = Query(10, gt=0, le=100)):
    """
    Read items with pagination.
    """
    return {"page": page, "limit": limit}

In this example, we have defined two query parameters: page and limit. The Query function is used to specify the default values and validation rules for these parameters. The gt and le parameters are used to specify the minimum and maximum values for limit.

Accessing comma separated list as query parameter

Query parameters in FastAPI can be of any type, including lists. To define a list query parameter, we can use the List function from the typing module. Here's an example:

from typing import List
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items")
async def read_items(tags: List[str] = Query(None)):
    """
    Read items with tags.
    """
    if tags:
        return {"tags": tags}
    else:
        return {"tags": []}

In this example, we have defined a query parameter called tags, which is a list of strings. The List function is used to specify the type of the list elements. The Query function is used to specify the default value, which is None in this case.

To pass a list query parameter to the API, we can use the same URL format as before, but separate the values with commas:

https://localhost:8000/items?tags=tag1,tag2,tag3

In this URL, tags is a query parameter that contains a list of three tags: tag1, tag2, and tag3. When the API receives this request, the tags parameter is automatically converted to a Python list.

Accessing key value pairs for a list as query parameter

We can also pass a list of values as a query parameter using multiple key value pairs with the same key. The same request from above will be as shown below

https://localhost:8000/items?tags=tag1&tags=tag2&tags=tag3

To access these list elements within FastAPI the following changes are required in the parameter types

from typing import List, Annotated, Union
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items")
async def read_items(tags: Annotated[Union[List[str], None], Query()] = None):
    """
    Read items with tags.
    """
    if tags:
        return {"tags": tags}
    else:
        return {"tags": []}

To declare a query parameter with a type of list, like in the example above, we need to explicitly use Query, otherwise it would be interpreted as a request body. Please check the FastAPI docs here for reference.

Making a request with multiple values for tags