API versioning strategy config-based prefix vs. v1/ folder module

[chetanr25]

A review comment on PR #574 pointed out the import strategy for the jobs router it was being added directly to api_router instead of going through v1_router. This got me looking at the last few merged PRs and the current codebase structure, where I noticed we now have two parallel structures for API routes. I also did some research across open-source FastAPI projects to see how they handle this.

The v1/ folder approach (introduced in PR #573) does achieve the /api/v1/... URL pattern that our OpenAPI contract requires. However, when I originally created the contracts and proposed the codebase structure in Discussion #501, I had a different approach in mind that I didn't get to implement at the time I intentionally did not include a v1/ versioning folder in the proposed structure.

Current state

Right now we have two parallel structures:

app/api/
  routes/          # proposed routes
  v1/
    routes/        # new routes /api/v1/system, /api/v1/health
  schemas/         # shared schemas (not versioned)
  router.py        # mounts both

This is inconsistent some endpoints are versioned, some aren't. If we commit to the v1/ folder approach, we'd need to migrate all existing routes, schemas, and potentially models into the versioned folder.

My proposal: config-based prefix (no versioning folder)

Add a single constant in config.py:

API_PREFIX = "/api/v1"

Mount all routes under this prefix in router.py:

app.include_router(api_router, prefix=settings.API_PREFIX)

Resulting structure stays flat:

app/api/
  routes/
    templates.py
    forms.py
    jobs.py
    system.py
  schemas/
    templates.py
    forms.py
    system.py
    common.py
  deps.py
  router.py

All endpoints still resolve to /api/v1/templates, /api/v1/forms, etc. matching our OpenAPI contract exactly. If we ever need to bump, we change one string.

Why not a v1/ folder?

Concern	Detail
Migration cost	Adopting v1/ now means moving all existing routes, schemas into it. Every open PR would conflict.
Unnecessary complexity	FireForm is a single-consumer desktop app. Frontend and backend deploy together. We'll never need to run v1 and v2 side by side.
Duplication risk	True API versioning means separate schemas per version, separate route modules a lot of overhead for a project our size.
Contribution friction	New contributors need to understand why some files are in api/routes/ and others in api/v1/routes/. One flat structure is simpler.

What stays the same

• URLs match the OpenAPI contract: /api/v1/templates, /api/v1/forms, etc.
• Internal layering unchanged: routes → services → repositories → database
• Schemas, models, services, core all stay where they are

[chetanr25]

Router Import Strategy

Addressing #574 (comment)
Separate from versioning, we should also align on how route modules are imported and registered in router.py. There are three approaches:

Option A: Module import + module.router (current approach)

from app.api.routes import forms, templates, jobs

api_router = APIRouter()
api_router.include_router(templates.router)
api_router.include_router(forms.router)
api_router.include_router(jobs.router)

Pros	Cons
Clear which module each router comes from	Two lines per route (import + include)
Easy to access other module-level attributes if needed	Import line grows long with many modules
Most common pattern in FastAPI projects	-

Option B: Direct router import with alias

from app.api.routes.forms import router as forms_router
from app.api.routes.templates import router as templates_router
from app.api.routes.jobs import router as jobs_router

api_router = APIRouter()
api_router.include_router(templates_router)
api_router.include_router(forms_router)
api_router.include_router(jobs_router)

Pros	Cons
Explicit - each import names exactly what it brings in	Verbose alias needed for every route to avoid name collisions
No intermediate module reference	More lines as route count grows
-	as aliases can drift from actual module names

Option C: Unique router names per module

# routes/forms.py
forms_router = APIRouter(prefix="/forms", tags=["forms"])

# routes/templates.py
templates_router = APIRouter(prefix="/templates", tags=["templates"])

# router.py
from app.api.routes.forms import forms_router
from app.api.routes.templates import templates_router

api_router = APIRouter()
api_router.include_router(templates_router)
api_router.include_router(forms_router)

This is the pattern used by v1_router in the current codebase each module exports a uniquely named router variable.

Pros	Cons
No alias needed, no name collision	Requires renaming router to <module>_router in every route file
Imports are explicit without module.router indirection	Breaks the standard FastAPI convention where route files export router
-	Touches every route file in the codebase large diff for no functional gain

Recommendation

Option A - it's the standard FastAPI pattern, scales cleanly, and avoids alias noise. One import line pulls in all modules, and module.router makes it obvious where each router lives.

from app.api.routes import forms, jobs, system, templates

api_router = APIRouter()
api_router.include_router(templates.router)
api_router.include_router(forms.router)
api_router.include_router(jobs.router)
api_router.include_router(system.router)

[chetanr25]

@marcvergees @abhishek-8081
Would love to have your feedback. I think this discussion is very important to have better maintainability over the period for FireForm

[marcvergees]

Clearly "Option A": faster, cleaner and modularized.

Can you @abhishek-8081 PR the changes so that what you created in a new folder v1 now is in the "normal" routes? (i.e. getting rid of this folder basically).

Thanks.
Marc