Defining Multiple API Endpoints with Different Paths and the Same Path Parameter in FastAPI

In FastAPI, declaring multiple API endpoints with different paths but the same path parameter can lead to unexpected route matching behavior.

Consider the following example:

# GET API Endpoint 1
@router.get("/project/{project_id}/{employee_id}")
async def method_one(project_id: str, employee_id: str, ...):

    # ...

# GET API Endpoint 2
@router.get("/project/details/{project_id}")
async def method_two(project_id: str, ...):

    # ...

# GET API Endpoint 3
@router.get("/project/metadata/{project_id}")
async def method_three(project_id: str, ...):

    # ...

In this scenario, when API endpoints 2 and 3 are called, they execute the controller method defined in endpoint 1, namely method_one(). This is due to how FastAPI evaluates endpoints in sequence.

Solution

To ensure proper route matching, you must declare endpoints in the order of their path specificity. Because endpoints are evaluated sequentially, endpoints with more specific paths should be declared first.

In the above example, the endpoint for /project/{project_id}/{employee_id} is more specific than the endpoint for /project/details/{project_id}. Therefore, the correct declaration order is:

# GET API Endpoint 1
@router.get("/project/details/{project_id}")
async def method_two(project_id: str, ...):

    # ...

# GET API Endpoint 2
@router.get("/project/metadata/{project_id}")
async def method_three(project_id: str, ...):

    # ...

# GET API Endpoint 3
@router.get("/project/{project_id}/{employee_id}")
async def method_one(project_id: str, employee_id: str, ...):

    # ...

By following this order, when endpoints 2 and 3 are called, the corresponding methods method_two() and method_three() will be executed as intended.