FastAPI API versioning with router prefixes

<p>I need to version my FastAPI API (v1, v2 eventually) without breaking existing clients when I introduce breaking changes. I want to organize routes in separate router modules per version and apply versioned URL prefixes.</p>

<p>Use router includes with version prefixes:</p> <div class="highlight"><pre><span></span><code><span class="c1"># api/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="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="kn">from</span><span class="w"> </span><span class="nn">.votes</span><span class="w"> </span><span class="kn">import</span> <span class="n">router</span> <span class="k">as</span> <span class="n">votes_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">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="n">v1_router</span><span class="o">.</span><span class="n">include_router</span><span class="p">(</span><span class="n">votes_router</span><span class="p">,</span> <span class="n">prefix</span><span class="o">=</span><span class="s1">'/votes'</span><span class="p">,</span> <span class="n">tags</span><span class="o">=</span><span class="p">[</span><span class="s1">'votes'</span><span class="p">])</span> <span class="c1"># api/app/main.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">FastAPI</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 are now at /api/v1/traces, /api/v1/search, etc.</span> <span class="c1"># For v2 (future):</span> <span class="c1"># app.include_router(v2_router, prefix='/api')</span> </code></pre></div> <p>Shared dependencies across versions:</p> <div class="highlight"><pre><span></span><code><span class="c1"># Shared auth works for both:</span> <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">require_auth</span><span class="p">(</span><span class="n">api_key</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="n">Header</span><span class="p">(</span><span class="n">alias</span><span class="o">=</span><span class="s1">'X-API-Key'</span><span class="p">)):</span> <span class="o">...</span> <span class="c1"># Apply at router level:</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> </code></pre></div> <p>Key points: - Include <code>prefix='/api'</code> on the app level so all API routes are under <code>/api</code> - Separate router modules per resource keep files manageable - Per-router <code>tags</code> keeps OpenAPI documentation organized - Apply auth at router level with <code>dependencies=[]</code> to avoid repeating it per route</p>