Router prefix and tags in FastAPI - Deep Dive

Overview - Router prefix and tags

What is it?

In FastAPI, a router prefix is a string added before all paths in a router to group related endpoints under a common URL segment. Tags are labels assigned to routes to organize and describe them in the automatic API documentation. Together, prefixes and tags help structure your API routes clearly and make the documentation easier to understand.

Why it matters

Without router prefixes and tags, your API routes can become messy and hard to manage, especially as your application grows. You would have to repeat common path parts for each route and your documentation would lack clear grouping, making it difficult for users and developers to find and understand endpoints. These features save time, reduce errors, and improve collaboration.

Where it fits

Before learning router prefixes and tags, you should understand basic FastAPI routing and path operations. After mastering prefixes and tags, you can explore advanced API design, dependency injection, and security features to build robust APIs.

Mental Model

Core Idea

Router prefixes add a shared starting path to a group of routes, and tags label these routes for clear grouping in documentation.

Think of it like...

Think of router prefixes like the street name in an address that groups houses together, and tags like the neighborhood name that helps people recognize and find related houses easily.

API Root
  ├─ /users (prefix: /users, tag: Users)
  │    ├─ GET /users/
  │    └─ POST /users/
  └─ /items (prefix: /items, tag: Items)
       ├─ GET /items/
       └─ POST /items/

Build-Up - 7 Steps

1

Foundation

Basic FastAPI Routing Setup

Concept: Learn how to create simple routes in FastAPI without prefixes or tags.

In FastAPI, you define routes using decorators like @app.get or @app.post with a path string. For example, @app.get('/hello') defines a GET endpoint at /hello that returns a response.

Result

You get a working API with endpoints accessible at specified paths.

Understanding how to define routes is essential before grouping or labeling them.

2

Foundation

Introduction to APIRouter

Concept: Discover how to use APIRouter to organize routes into groups.

FastAPI provides APIRouter to create modular route groups. You create a router with APIRouter(), add routes to it, then include it in the main app with app.include_router(router).

Result

Routes are grouped logically but still appear at their full paths without shared prefixes.

Using routers helps keep code organized but does not yet change URL paths or documentation grouping.

3

Intermediate

Applying Router Prefixes

🤔Before reading on: Do you think adding a prefix changes the route path or just the documentation? Commit to your answer.

Concept: Learn how to add a prefix to all routes in a router to share a common URL segment.

When including a router, you can specify a prefix like app.include_router(router, prefix='/users'). This adds '/users' before every route path in that router, so a route defined as @router.get('/') becomes accessible at '/users/'.

Result

All routes in the router share the prefix in their URL paths, making URLs consistent and shorter to write.

Knowing that prefixes change the actual URL paths helps avoid mistakes in endpoint access and improves API structure.

4

Intermediate

Using Tags for Documentation

🤔Before reading on: Do you think tags affect the URL paths or only the API docs? Commit to your answer.

Concept: Tags label routes to group them in the automatic API documentation without changing their URLs.

You can add tags when defining routes or when including routers, e.g., @router.get('/', tags=['Users']) or app.include_router(router, tags=['Users']). These tags appear in the OpenAPI docs to group endpoints under named sections.

Result

API documentation shows grouped endpoints by tags, making it easier to navigate and understand the API.

Understanding that tags only affect documentation helps keep URL design separate from documentation clarity.

5

Intermediate

Combining Prefixes and Tags

Concept: Use prefixes and tags together to organize routes both in URLs and documentation.

When including a router, you can specify both prefix and tags: app.include_router(router, prefix='/items', tags=['Items']). This means all routes start with '/items' and appear grouped under 'Items' in docs.

Result

Your API URLs are clean and grouped logically, and your docs reflect this grouping clearly.

Combining these features creates a professional and maintainable API structure.

6

Advanced

Nested Routers with Prefixes and Tags

🤔Before reading on: Can routers be nested with their own prefixes and tags? Commit to your answer.

Concept: Routers can be nested by including one router inside another, each with its own prefix and tags, creating hierarchical URL and doc structures.

You can create a router for '/users' and inside it include another router for '/settings' with its own prefix. The final path becomes '/users/settings'. Tags can be combined or separated to reflect this hierarchy in docs.

Result

Complex APIs can be modularized with clear URL hierarchies and documentation groups.

Knowing nested routers exist helps design scalable APIs with clean separation of concerns.

7

Expert

Tag Inheritance and Documentation Merging

🤔Before reading on: Do tags from included routers merge automatically or override each other? Commit to your answer.

Concept: FastAPI merges tags from routers and routes, but tag inheritance can be subtle and affect documentation grouping.

When you include a router with tags and routes inside also have tags, FastAPI combines them in docs. However, if tags conflict or overlap, the order and specificity affect how endpoints appear grouped. Understanding this helps avoid confusing docs.

Result

You get well-organized API docs that reflect your intended grouping without duplication or missing sections.

Understanding tag merging prevents documentation bugs that confuse API users and developers.

Under the Hood

FastAPI's routing system builds a tree of routes. When you add a prefix to a router, it prepends that prefix string to every route path in that router before registering them. Tags are metadata attached to route objects and collected when generating OpenAPI schema for documentation. The OpenAPI generator groups routes by tags to create sections in the docs.

Why designed this way?

Prefixes avoid repeating common path parts, reducing errors and improving maintainability. Tags separate URL design from documentation concerns, allowing flexible grouping without changing routes. This separation follows the principle of single responsibility and keeps code clean.

Main App
  │
  ├─ Include Router (prefix='/users', tags=['Users'])
  │     ├─ Route: GET '/' → '/users/'
  │     └─ Route: POST '/create' → '/users/create'
  │
  ├─ Include Router (prefix='/items', tags=['Items'])
        ├─ Route: GET '/' → '/items/'
        └─ Route: POST '/add' → '/items/add'

Documentation Generator
  ├─ Groups routes by tags:
  │     ├─ Users
  │     └─ Items

Myth Busters - 4 Common Misconceptions

Quick: Does adding a tag to a route change its URL path? Commit to yes or no.

Common Belief: Tags change the URL path of the route to include the tag name.

Reality: Tags only affect how routes are grouped in the API documentation; they do not change the URL path at all.

Why it matters: Confusing tags with URL paths can lead to incorrect assumptions about how to access endpoints, causing bugs and wasted time.

Quick: If you add a prefix to a router, do you need to repeat it in each route path? Commit to yes or no.

Common Belief: You must repeat the prefix in each route path even if the router has a prefix.

Reality: The router prefix automatically prepends to all route paths inside it, so repeating it causes duplicated paths.

Why it matters: Repeating prefixes leads to incorrect URLs like '/users/users/' which break the API and confuse users.

Quick: When including multiple routers with the same tag, do their routes merge under one group in docs? Commit to yes or no.

Common Belief: Routes with the same tag from different routers appear separately in documentation.

Reality: FastAPI merges routes with the same tag into a single group in the documentation.

Why it matters: Misunderstanding this can cause redundant tags or messy docs, making API harder to navigate.

Quick: Does nesting routers with prefixes always combine their prefixes automatically? Commit to yes or no.

Common Belief: Nested routers automatically combine prefixes without extra configuration.

Reality: You must explicitly include nested routers with their prefixes; FastAPI does not auto-merge prefixes from nested routers.

Why it matters: Assuming automatic prefix merging can cause missing or incorrect routes, leading to runtime errors.

Expert Zone

1

Tags can be assigned both at the router level and individual route level; understanding how FastAPI merges these tags is key to clean documentation.

2

Router prefixes are simple string concatenations, so careful use of slashes is needed to avoid double slashes or missing slashes in URLs.

3

When using nested routers, the order of inclusion affects route resolution and documentation grouping, which can cause subtle bugs if overlooked.

When NOT to use

Avoid using router prefixes when routes need to be accessible at multiple base paths; instead, define separate routers or use path parameters. For tags, if you want dynamic or conditional grouping, consider custom OpenAPI schema generation instead of static tags.

Production Patterns

In production, teams use router prefixes to separate API versions (e.g., '/v1', '/v2') and tags to group endpoints by feature or team ownership. Nested routers help modularize large APIs by domain, improving maintainability and collaboration.

Connections

REST API Design

Router prefixes correspond to resource path grouping in REST, and tags relate to resource categorization in API docs.

Understanding router prefixes and tags deepens comprehension of RESTful URL design and how documentation reflects API structure.

Modular Programming

Routers with prefixes and tags enable modular code organization, similar to modules or packages in programming languages.

Recognizing this connection helps appreciate how API design parallels software architecture principles.

Library Classification Systems

Tags in FastAPI are like library classification labels that group books by topic, aiding discovery and organization.

Seeing tags as classification labels reveals how organizing information efficiently is a universal challenge across fields.

Common Pitfalls

#1 Forgetting to add a leading slash in router prefix causing incorrect URLs.

Wrong approach:

app.include_router(router, prefix='users')

Correct approach:

app.include_router(router, prefix='/users')

Root cause:

The prefix string must start with a slash to form valid URL paths; missing it concatenates paths incorrectly.

#2 Assigning tags only to routers but expecting them to appear on all routes automatically.

Wrong approach:

app.include_router(router, tags=['Users'])
@router.get('/profile')
def profile(): pass # no tags here

Correct approach:

@router.get('/profile', tags=['Users'])
def profile(): pass

Root cause:

Tags on routers do not automatically apply to individual routes unless specified; routes need explicit tags or inherit from router inclusion.

#3 Repeating prefix in route decorator causing duplicated URL segments.

Wrong approach:

@router.get('/users')
# with router prefix '/users' included
app.include_router(router, prefix='/users')

Correct approach:

@router.get('/')
app.include_router(router, prefix='/users')

Root cause:

Route paths are relative to router prefix; repeating prefix in route causes wrong URLs.

Key Takeaways

Router prefixes in FastAPI add a shared path segment to all routes in a router, simplifying URL management.

Tags label routes for grouping in API documentation without affecting their URL paths.

Combining prefixes and tags helps organize both the API structure and its documentation clearly.

Nested routers allow building complex, modular APIs with hierarchical URL and documentation grouping.

Understanding how FastAPI merges tags and applies prefixes prevents common bugs and improves API usability.