The Ultimate FastAPI Tutorial Part 2 - URL Path Parameters

Introduction

Welcome to the Ultimate FastAPI tutorial series. This post is part 2. The series is a project-based tutorial where we will build a cooking recipe API. Each post gradually adds more complex functionality, showcasing the capabilities of FastAPI, ending with a realistic, production-ready API. The series is designed to be followed in order, but if you already know FastAPI you can jump to the relevant part.

Code

Project github repo directory for this part

Tutorial Series Contents

Optional Preamble: FastAPI vs. Flask

Beginner Level Difficulty

Part 1: Hello World

Part 2: URL Path Parameters & Type Hints

Part 3: Query Parameters

Part 4: Pydantic Schemas & Data Validation

Part 5: Basic Error Handling

Part 6: Jinja Templates

Part 6b: Basic FastAPI App Deployment on Linode

Intermediate Level Difficulty

Part 7: Setting up a Database with SQLAlchemy and its ORM

Part 8: Production app structure and API versioning

Part 9: Creating High Performance Asynchronous Logic via async def and await

Part 10: Authentication via JWT

Part 11: Dependency Injection and FastAPI Depends

Part 12: Setting Up A React Frontend

Part 13: Using Docker, Uvicorn and Gunicorn to Deploy Our App to Heroku

Part 14: Using Docker and Uvicorn to Deploy Our App to IaaS (Coming soon)

Part 15: Exploring the Open Source Starlette Toolbox - GraphQL (Coming soon)

Part 16: Alternative Backend/Python Framework Comparisons (i.e. Django) (Coming soon)

Post Contents

Practical Section - An Endpoint With Query Params

Using Basic Type Hints in FastAPI

Practical Section - An Endpoint With Path Params

If you haven’t already, go ahead and clone the example project repo. See the README file for local setup.

In the app/main.py file, you will find the following new code:

from fastapi import FastAPI
# skipping...

# 1
RECIPES = [
    {
        "id": 1,
        "label": "Chicken Vesuvio",
        "source": "Serious Eats",
        "url": "http://www.seriouseats.com/recipes/2011/12/chicken-vesuvio-recipe.html",
    },
    {
        "id": 2,
        "label": "Chicken Paprikash",
        "source": "No Recipes",
        "url": "http://norecipes.com/recipe/chicken-paprikash/",
    },
    {
        "id": 3,
        "label": "Cauliflower and Tofu Curry Recipe",
        "source": "Serious Eats",
        "url": "http://www.seriouseats.com/recipes/2011/02/cauliflower-and-tofu-curry-recipe.html",
    },
]

# skipping ahead ...


# 2 - New addition, path parameter
# https://fastapi.tiangolo.com/tutorial/path-params/
@api_router.get("/recipe/{recipe_id}", status_code=200)
def fetch_recipe(*, recipe_id: int) -> dict:  # 3
    """
    Fetch a single recipe by ID
    """

    # 4
    result = [recipe for recipe in RECIPES if recipe["id"] == recipe_id]
    if result:
        return result[0]

# ...

Let’s break this down:

1. We’ve created some example recipe data in the RECIPE list of dictionaries. For now, this is basic and minimal but serves our purposes for learning. Later in the tutorial series we will expand this dataset and store it in a database.
2. We’ve created a new GET endpoint /recipe/{recipe_id}. Here the curly braces indicate the parameter value, which needs to match one of the arguments taken by the endpoint function fetch_recipe.
3. The fetch_recipe function defines the logic for the new endpoint. The type hints for the function arguments which match the URL path parameters are used by FastAPI to perform automatic validation and conversion. We’ll look at this in action in a moment.
4. We simulate fetching data by ID from a database with a simple list comprehension with an ID conditional check. The data is then serialized and returned as JSON by FastAPI.

Having done all that (and followed the README setup instructions), you can run the code in the example repo with this command (be sure to cd into the part 2 folder): poetry run ./run.sh

Navigate to localhost:8001/docs

Give the endpoint a try:

• Expand the GET endpoint by clicking on it
• Click on the “Try It Out” button
• Enter the value “1” for the recipe_id
• Press the large “Execute” button
• Press the smaller “Execute” button that appears

You should see the Chicken Vesuvio recipe in the response.

Using Basic Type Hints in FastAPI

Let’s add a print statement to further understand what’s happening in the endpoint:

@api_router.get("/recipe/{recipe_id}", status_code=200)
def fetch_recipe(*, recipe_id: int) -> dict:
    """
    Fetch a single recipe by ID
    """
    print(type(recipe_id))  # ADDED

    result = [recipe for recipe in RECIPES if recipe["id"] == recipe_id]
    if result:
        return result[0]

Now when you try out the endpoint, you’ll see in your terminal:

Now change the type hint to a string:

def fetch_recipe(*, recipe_id: str) -> dict:
# skipping...

Now in your terminal, when you call the endpoint you’ll see a string being printed.

This is because FastAPI is coercing the input parameter type based on the function argument type hints. This is a handy way of preventing input errors. You’ll notice that after you have changed the recipe_id to a string, you no longer get responses to your API calls.

Quiz: Why do you think this is?

Stop reading and try and figure it out without reading below

OK, here is the answer

Because the recipe_id is a string, the == match in the list comprehension is no longer matching the integer ID values in the RECIPES list of dictionaries. This is a very simple example of how FastAPI’s integration with type hints can prevent many input mistakes, without us having to write additional checks in the code (less code means fewer bugs).

We’re just scratching the surface of how FastAPI uses type hints, more on this in the next couple of parts of the tutorial.

Further Reading - Python Type Declarations

• Python type declarations were introduced in Python Enhancement Proposal (PEP) 484.
• There’s a very readable overview of the theory of type hints in PEP 483.

Continue Learning FastAPI

In the next part of the tutorial, we’ll shift from path parameters to query parameters.

Go to part 3

If you’re interested in dealing with POST requests (where your request body is validated) that’s covered in part 4