Application route modules

What

An application route module is a class that extends FusionBaseApi and is registered with a path template. Convention HTTP methods and optional custom HTTP routes become mounted endpoints in fusion-core.

Why

Grouping handlers on a class keeps one resource’s HTTP surface cohesive and lets [module] derive a stable path stem from the class name.

When

Use a route module for each HTTP resource (or cohesive group of endpoints) your application exposes.

Create a route module (Python)

# src/modules/users/users.py
from fusion_framework.api import FusionBaseApi
from fusion_framework.route import route
from fusion_framework.http_route import http_get, http_post
from fusion_framework import status


@route(
    "api/[module]/",
    tags=["users"],
    desc="User resource",
    version="v1",
)
class UserModule(FusionBaseApi):
    def get(self):
        return self.response({"users": []}, status=status.HTTP_SUCCESS)

    @http_get("profile/[action]", title="Current profile action")
    def ProfileAction(self):
        return self.response({"profile": True}, status=status.HTTP_SUCCESS)

    @http_post("create/[action]", title="Create user")
    def CreateAction(self):
        return self.response({"created": True}, status=status.HTTP_SUCCESS)

# main.py
import src.modules.users.users  # noqa: F401 — runs @route

from fusion_framework.app import FusionApp
from fusion_framework.config import get_settings, load_settings_module

def main() -> None:
    load_settings_module("settings")
    FusionApp(get_settings()).listen()

if __name__ == "__main__":
    main()

Paths produced

Handler	Method	Path (with `version="v1"`)
`get`	GET	`/v1/api/user/`
`ProfileAction`	GET	`/v1/api/user/profile/profile`
`CreateAction`	POST	`/v1/api/user/create/create`

UserModule → [module] = user. ProfileAction → [action] = profile. CreateAction → [action] = create.

Convention vs custom routes

Mode	Mechanism	Example
Convention	Methods named `get`, `post`, `put`, `patch`, `delete`, `head`, `options`	`GET /api/user/`
Custom	`@http_get` … `@http_options` / `httpGet` … `httpOptions` / `[HttpGet]` … `[HttpOptions]`	`GET /api/user/profile/profile`, `POST /api/user/create/create`

Both can coexist on the same class. Details: Python Router · Custom HTTP routes.

Route options

Option	Purpose
`tags`, `title`, `desc`	OpenAPI metadata
`version`	Path prefix + Swagger version navbar entry
`deprecated`	Mark operations deprecated
`middleware`	Route-scoped middleware list
`roles`	Appends `require_roles(...)` middleware

Registration checklist

Create file under src/modules/...
Subclass FusionBaseApi
Apply @route / route() / [Route]
Import the module from the entrypoint before listen()
(C#) call Route.Register<T>() explicitly

TypeScript / C#

Same semantics with different syntax — see language router pages:

Best practices

One primary resource per class
Keep startup out of module files
Prefer [module] over hard-coding resource names
Use version= for breaking API changes