FastAPI API versioning with router prefixes and shared middleware

<p>I need to version my FastAPI API (v1, v2 eventually) without breaking existing clients. I want routes organized in separate modules per version with versioned URL prefixes and shared authentication.</p>

<p>Router includes with version prefixes:</p> <div class="highlight"><pre><span></span><code><span class="c1"># app/routers/v1/__init__.py</span> <span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">APIRouter</span><span class="p">,</span> <span class="n">Depends</span> <span class="kn">from</span><span class="w"> </span><span class="nn">app.auth</span><span class="w"> </span><span class="kn">import</span> <span class="n">require_auth</span> <span class="kn">from</span><span class="w"> </span><span class="nn">.traces</span><span class="w"> </span><span class="kn">import</span> <span class="n">router</span> <span class="k">as</span> <span class="n">traces_router</span> <span class="kn">from</span><span class="w"> </span><span class="nn">.search</span><span class="w"> </span><span class="kn">import</span> <span class="n">router</span> <span class="k">as</span> <span class="n">search_router</span> <span class="n">v1_router</span> <span class="o">=</span> <span class="n">APIRouter</span><span class="p">(</span> <span class="n">prefix</span><span class="o">=</span><span class="s1">'/v1'</span><span class="p">,</span> <span class="n">dependencies</span><span class="o">=</span><span class="p">[</span><span class="n">Depends</span><span class="p">(</span><span class="n">require_auth</span><span class="p">)],</span> <span class="c1"># Auth for all v1 routes</span> <span class="p">)</span> <span class="n">v1_router</span><span class="o">.</span><span class="n">include_router</span><span class="p">(</span><span class="n">traces_router</span><span class="p">,</span> <span class="n">prefix</span><span class="o">=</span><span class="s1">'/traces'</span><span class="p">,</span> <span class="n">tags</span><span class="o">=</span><span class="p">[</span><span class="s1">'traces'</span><span class="p">])</span> <span class="n">v1_router</span><span class="o">.</span><span class="n">include_router</span><span class="p">(</span><span class="n">search_router</span><span class="p">,</span> <span class="n">prefix</span><span class="o">=</span><span class="s1">'/traces'</span><span class="p">,</span> <span class="n">tags</span><span class="o">=</span><span class="p">[</span><span class="s1">'search'</span><span class="p">])</span> <span class="c1"># app/main.py</span> <span class="kn">from</span><span class="w"> </span><span class="nn">app.routers.v1</span><span class="w"> </span><span class="kn">import</span> <span class="n">v1_router</span> <span class="n">app</span> <span class="o">=</span> <span class="n">FastAPI</span><span class="p">()</span> <span class="n">app</span><span class="o">.</span><span class="n">include_router</span><span class="p">(</span><span class="n">v1_router</span><span class="p">,</span> <span class="n">prefix</span><span class="o">=</span><span class="s1">'/api'</span><span class="p">)</span> <span class="c1"># Routes: /api/v1/traces, /api/v1/traces/search, etc.</span> <span class="c1"># Per-router auth scope:</span> <span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">APIRouter</span> <span class="n">traces_router</span> <span class="o">=</span> <span class="n">APIRouter</span><span class="p">()</span> <span class="nd">@traces_router</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s1">''</span><span class="p">)</span> <span class="c1"># POST /api/v1/traces</span> <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_trace</span><span class="p">(</span><span class="n">body</span><span class="p">:</span> <span class="n">TraceCreate</span><span class="p">,</span> <span class="n">user</span><span class="p">:</span> <span class="n">CurrentUser</span><span class="p">,</span> <span class="n">db</span><span class="p">:</span> <span class="n">DbSession</span><span class="p">):</span> <span class="o">...</span> <span class="nd">@traces_router</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'/</span><span class="si">{trace_id}</span><span class="s1">'</span><span class="p">)</span> <span class="c1"># GET /api/v1/traces/{id}</span> <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_trace</span><span class="p">(</span><span class="n">trace_id</span><span class="p">:</span> <span class="n">uuid</span><span class="o">.</span><span class="n">UUID</span><span class="p">,</span> <span class="n">db</span><span class="p">:</span> <span class="n">DbSession</span><span class="p">):</span> <span class="o">...</span> </code></pre></div> <p>Key points: - prefix='/api' on the app include so all routes are under /api - Separate router modules per resource keep files small - Per-router tags group endpoints in Swagger UI - Apply auth at router level with dependencies=[] to avoid repetition - When adding v2, include a v2_router alongside v1_router</p>