Unit 6: Path Parameters

Introduction

Path parameters are essentially parts of the URL path that are variables. You can use these variables to capture values specified at specific positions in the path. This capability is crucial for creating RESTful APIs where the URL path includes identifiers that point to specific resources or data. For instance, in a blog API, you might have a URL path like /posts/{post_id}, where {post_id} is a path parameter representing the ID of a post.

FastAPI simplifies the declaration and extraction of path parameters using Python type annotations, providing automatic data validation, serialization, and documentation features. This not only boosts development speed but also ensures that APIs are more reliable and easier to use.

Path parameters

You can declare path parameters (or variables) with the same syntax used by Python format strings:

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id):
    return {"item_id": item_id}

The value of the path parameter item_id will be passed to your function as the argument item_id.

To run the above program, open a CMD/Terminal and execute the command below:

uvicorn main:app --reload

When you go to http://127.0.0.1:8000/items/foo, you will see a response of {"item_id":"foo"}.

Path parameters with types

You can declare the type of a path parameter in the function, using standard Python type annotations:

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item():
    return {"item_id": item_id}

In this case, item_id is declared to be an int. If you request an item_id that is not an integer value, such as http://127.0.0.1:8000/items/foo, you will receive a descriptive HTTP error as follows:

{
    "detail": [
        {
            "type": "int_parsing",
            "loc": [
                "path",
                "item_id"
            ],
            "msg": "Input should be a valid integer, unable to parse string as an integer",
            "input": "foo",
            "url": "https://errors.pydantic.dev/2.5/v/int_parsing"
        }
    ]
}

So, with the same Python type declaration, FastAPI gives you data validation. Notice that the error also clearly states exactly the point where the validation didn't pass. This is incredibly helpful while developing and debugging code that interacts with your API.

Documentation

You can get an automatic, interactive, API documentation by visiting http://127.0.0.1:8000/docs in your browser, as shown in Fig. 1.

Order matters

When creating path operations, you can find situations where you have a fixed path. For example:

/users/me is used to get data about the current user.
/users/{user_id} is used to get data about a specific user by giving an user_id.

from fastapi import FastAPI

app = FastAPI()


@app.get("/users/me")
async def read_user_me():
    return {"user_id": "the current user"}


@app.get("/users/{user_id}")
async def read_user(user_id: str):
    return {"user_id": user_id}

Predefined values

If your path operation requires a specific set of values for a path parameter, leveraging a standard Python Enum allows you to predefine these valid options.

Begin by creating a new Python file and naming it ex01_enum.py. Then, proceed to add the following code to the file:

# Filename: ex01_enum.py
from fastapi import FastAPI
from enum import Enum


class MyColor(str, Enum):
    red = "red"
    green = "green"
    blue = "blue"


app = FastAPI()


@app.get("/colors/{color}")
async def get_color(color: MyColor):
    if color is MyColor.red:
        return {"color": color, "message": "red"}
    elif color.value == "green":
        return {"color": color, "message": "green"}
    elif color is MyColor.blue:
        return {"color": color, "message": "blue"}
    else:
        return {"message": "color is not defined."}

You can interact with the program mentioned above in two scenarios. First, visit http://127.0.0.1:8000/colors/red; this is a valid case, and you will receive a response as defined in the program. Second, visit http://127.0.0.1:8000/colors/foo; in this case, you will receive an error message, as follows:

{
    "detail": [
        {
            "type": "enum",
            "loc": [
                "path",
                "color"
            ],
            "msg": "Input should be 'red', 'green' or 'blue'",
            "input": "foo",
            "ctx": {
                "expected": "'red', 'green' or 'blue'"
            }
        }
    ]
}

Since we have defined a list of possible values for the color variable, the API Docs generated by FastAPI can show them nicely, as shown in Fig. 2.

Summary

Path parameters in FastAPI provide a method for defining dynamic and flexible routes in your API. By leveraging Python's type annotations, FastAPI offers a straightforward, efficient, and error-resistant way to utilize path parameters, enhancing both the developer experience and the functionality of the APIs built with this framework.

Exercise

Let's assume you have a path such as /files/{file_path}, where {file_path} includes a directory path like home/usr/myfile.txt. Consequently, the URL for that file would be /files/home/usr/myfile.txt. However, OpenAPI does not support a method to declare a path parameter that contains a path within it. To address this issue, you can utilize one of the internal tools provided by Starlette. Implement a program to demonstrate how Starlette can be used in this scenario.

PreviousUnit 5: Hello World!NextUnit 7: Query Parameters

Last updated 1 year ago