Route ordering and priority in FastAPI - Step-by-Step Execution

Concept Flow - Route ordering and priority

Define routes in order

↓

Incoming request arrives

↓

Check first route pattern

↓

Run first route handler

No↓

Check next route pattern

↓

Run matched route handler

No↓

404 Not Found

FastAPI checks routes in the order they are defined. The first matching route handles the request. If none match, a 404 error is returned.

Execution Sample

FastAPI

from fastapi import FastAPI
app = FastAPI()

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

@app.get("/items/special")
async def read_special():
    return {"message": "special item"}

Defines two routes: a dynamic route for any item_id and a specific route for '/items/special'. The order affects which handler runs for '/items/special'.

Execution Table

Step	Request Path	Route Checked	Match?	Handler Run	Response
1	/items/special	/items/{item_id}	Yes	read_item	{"item_id": "special"}
2	/items/special	/items/special	No	None	Not reached
3	/items/123	/items/{item_id}	Yes	read_item	{"item_id": "123"}
4	/items/123	/items/special	No	None	Not reached
5	/items/unknown	/items/{item_id}	Yes	read_item	{"item_id": "unknown"}
6	/items/unknown	/items/special	No	None	Not reached
7	/unknown	/items/{item_id}	No	None	Not matched
8	/unknown	/items/special	No	None	Not matched
9	/unknown	No more routes	N/A	None	404 Not Found

💡 Request handled by first matching route or returns 404 if none match.

Variable Tracker

Variable	Start	After Step 1	After Step 3	After Step 5	After Step 7	Final
request_path	None	/items/special	/items/123	/items/unknown	/unknown	/unknown
matched_route	None	/items/{item_id}	/items/{item_id}	/items/{item_id}	None	None
handler_run	None	read_item	read_item	read_item	None	None
response	None	{"item_id": "special"}	{"item_id": "123"}	{"item_id": "unknown"}	None	404 Not Found

Key Moments - 3 Insights

Why does the dynamic route '/items/{item_id}' handle the '/items/special' request instead of the specific '/items/special' route?

Because the dynamic route is defined before the specific route, FastAPI matches it first and stops checking further routes, as shown in execution_table step 1.

What happens if no route matches the incoming request path?

FastAPI returns a 404 Not Found error, as shown in execution_table step 9 where '/unknown' matches no routes.

How can we ensure the specific route '/items/special' handles requests to that path?

Define the specific route before the dynamic route so it matches first, preventing the dynamic route from capturing '/items/special'.

Visual Quiz - 3 Questions

Look at the execution_table, what handler runs for the request path '/items/special' at step 1?

A 404 Not Found

B read_item

C read_special

D None

💡 Hint

Check the 'Handler Run' column at step 1 in the execution_table.

At which step does the request path '/unknown' result in a 404 Not Found?

A Step 9

B Step 8

C Step 7

D Step 6

💡 Hint

Look for the row where 'Response' is '404 Not Found' in the execution_table.

If we move the '/items/special' route above '/items/{item_id}', what changes in the execution_table for '/items/special'?

A Step 1 still matches dynamic route and runs read_item

B No route matches and returns 404

C Step 1 matches '/items/special' route and runs read_special

D Both routes run for the same request

💡 Hint

Consider route order priority explained in concept_flow and key_moments.

Concept Snapshot

FastAPI matches routes in the order they are defined.
The first route pattern that matches the request path handles it.
Specific routes should be defined before dynamic ones to get priority.
If no route matches, FastAPI returns a 404 error.
Route order affects which handler runs for overlapping paths.

Full Transcript

In FastAPI, routes are checked in the order they are defined. When a request comes in, FastAPI looks at each route pattern one by one. If the request path matches a route, FastAPI runs that route's handler and stops checking further routes. If no routes match, it returns a 404 Not Found error. For example, if a dynamic route like '/items/{item_id}' is defined before a specific route like '/items/special', the dynamic route will handle requests to '/items/special' because it matches first. To give priority to specific routes, define them before dynamic routes. This ordering controls which handler runs for overlapping paths.