Scaffold a New REST API Controller

Generate a new controller with endpoints. The resource name should be provided via $ARGUMENTS.

Step 1: Read Reference Materials

1. Read the API scope guide: packages/api/CLAUDE.md
2. Study these reference controllers:
   • CRUD: packages/api/swiss_ai_hub/api/routes/agent/agent_controller.py
   • Simple: packages/api/swiss_ai_hub/api/routes/role/role_controller.py
   • Complex: packages/api/swiss_ai_hub/api/routes/thread/thread_controller.py
   • Base class: packages/core/swiss_ai_hub/core/routes/controller.py
   • Registration: packages/api/app/main.py
3. Extract the resource name from $ARGUMENTS and derive snake_case (dirs/files) and CamelCase (classes)

Step 2: Create Directory Structure

packages/api/swiss_ai_hub/api/routes/<resource>/
├── __init__.py
├── <resource>_controller.py
├── <resource>_service.py
└── dto/
    ├── __init__.py
    ├── <resource>_dto.py
    ├── create_<resource>_request.py
    ├── update_<resource>_request.py
    └── paginated_<resource>s_response.py

Step 3: Create the Controller

File: packages/api/swiss_ai_hub/api/routes/<resource>/<resource>_controller.py

from typing import Annotated, Self

from swiss_ai_hub.core.auth.dependencies.auth_handler import AuthHandler
from swiss_ai_hub.core.auth.identity.user_identity import UserIdentity
from swiss_ai_hub.core.i18n.locale_handler import LocaleHandler
from swiss_ai_hub.core.routes.controller import Controller
from fastapi import Depends, Response, Security, status

from swiss_ai_hub.api.i18n.api_locale_string import ApiLocaleString
from swiss_ai_hub.api.i18n.dependencies.use_locale import use_locale
from swiss_ai_hub.api.pagination.type.page_number import PageNumber
from swiss_ai_hub.api.pagination.type.page_size import PageSize
from swiss_ai_hub.api.routes.<resource>.dto.create_<resource>_request import Create<Resource>Request
from swiss_ai_hub.api.routes.<resource>.dto.<resource>_dto import <Resource>DTO
from swiss_ai_hub.api.routes.<resource>.dto.paginated_<resource>s_response import Paginated<Resource>sResponse
from swiss_ai_hub.api.routes.<resource>.dto.update_<resource>_request import Update<Resource>Request
from swiss_ai_hub.api.routes.<resource>.<resource>_service import <Resource>Service


class <Resource>Controller(Controller):
    """Controller for <resource> management."""

    name = ApiLocaleString.from_i18n_path("api.controllers.<resource>.name")
    description = ApiLocaleString.from_i18n_path("api.controllers.<resource>.description")
    icon = "mage:icon-name"

    def __init__(
        self,
        *,
        auth: AuthHandler,
        route: str = "/<resource>s",
        additionally_required_permission: str | None = None,
    ):
        super().__init__(auth=auth, route=route, additionally_required_permission=additionally_required_permission)

    # ==================== LIST ====================

    def get_<resource>s(self, route: str = "/") -> Self:
        @self.router.get(route, tags=self.tags)
        async def get_<resource>s(
            user: Annotated[UserIdentity, Security(self.user_with_permission("aihub.user.?>"))],
            t: Annotated[LocaleHandler, Depends(use_locale)],
            page: PageNumber = 1,
            page_size: PageSize = 20,
        ) -> Paginated<Resource>sResponse:
            """Retrieve a paginated list of <resource>s."""
            total, items = await <Resource>Service.get_paginated_<resource>s(
                user_id=user.id, t=t, page=page, page_size=page_size,
            )
            total_pages = (total + page_size - 1) // page_size
            return Paginated<Resource>sResponse(
                <resource>s=items, total=total, page=page,
                page_size=page_size, total_pages=total_pages,
            )
        return self

    # ==================== GET ====================

    def get_<resource>(self, route: str = "/{<resource>_id}") -> Self:
        @self.router.get(route, tags=self.tags)
        async def get_<resource>(
            <resource>_id: str,
            _: Annotated[UserIdentity, Security(self.user_with_permission("aihub.user.<resource>.{<resource>_id}"))],
            t: Annotated[LocaleHandler, Depends(use_locale)],
        ) -> <Resource>DTO:
            """Retrieve details for a specific <resource>."""
            return await <Resource>Service.get_<resource>_by_id(<resource>_id, t)
        return self

    # ==================== CREATE ====================

    def create_<resource>(self, route: str = "/") -> Self:
        @self.router.post(route, tags=self.tags, status_code=status.HTTP_201_CREATED)
        async def create_<resource>(
            request: Create<Resource>Request,
            user: Annotated[UserIdentity, Security(self.user_with_permission("aihub.admin.<resource>"))],
            t: Annotated[LocaleHandler, Depends(use_locale)],
        ) -> <Resource>DTO:
            """Create a new <resource>."""
            return await <Resource>Service.create_<resource>(request, user, t)
        return self

    # ==================== UPDATE ====================

    def update_<resource>(self, route: str = "/{<resource>_id}") -> Self:
        @self.router.put(route, tags=self.tags)
        async def update_<resource>(
            <resource>_id: str,
            request: Update<Resource>Request,
            _: Annotated[UserIdentity, Security(self.user_with_permission("aihub.admin.<resource>.{<resource>_id}"))],
            t: Annotated[LocaleHandler, Depends(use_locale)],
        ) -> <Resource>DTO:
            """Update an existing <resource>."""
            return await <Resource>Service.update_<resource>(<resource>_id, request, t)
        return self

    # ==================== DELETE ====================

    def delete_<resource>(self, route: str = "/{<resource>_id}") -> Self:
        @self.router.delete(route, tags=self.tags, status_code=status.HTTP_204_NO_CONTENT)
        async def delete_<resource>(
            <resource>_id: str,
            _: Annotated[UserIdentity, Security(self.user_with_permission("aihub.admin.<resource>.{<resource>_id}"))],
        ) -> Response:
            """Delete a <resource>."""
            await <Resource>Service.delete_<resource>(<resource>_id)
            return Response(status_code=status.HTTP_204_NO_CONTENT)
        return self

Controller Architecture Rules

1. Inherit from Controller: Always extend swiss_ai_hub.core.routes.controller
2. Fluent builder: Every endpoint method returns Self for chaining
3. Metadata: Set name (ApiLocaleString), description, icon (Iconify)
4. Named-only constructor args: Use * to enforce keyword arguments
5. Default route: Set in constructor route: str = "/<resource>s"
6. Inner function pattern: Endpoint function is defined inside the method
7. Permission templates: Use {path_param} placeholders for dynamic permission checks
8. Tags: Always pass tags=self.tags to router decorators
9. Status codes: 201 for create, 204 for delete, 200 (default) for get/update

Permission Patterns

User Identity Usage

# When you need the identity (e.g., filter by user):
user: Annotated[UserIdentity, Security(self.user_with_permission("aihub.user.?>"))]
# Access: user.id, user.name, user.email, user.roles

# When you only need permission check:
_: Annotated[UserIdentity, Security(self.user_with_permission("aihub.admin.<resource>"))]

Step 4: Register in main.py

Edit packages/api/app/main.py:

from swiss_ai_hub.api.routes.<resource>.<resource>_controller import <Resource>Controller

runner.mount(
    # ... existing controllers ...
    <Resource>Controller(auth=auth)
        .get_<resource>s()
        .get_<resource>()
        .create_<resource>()
        .update_<resource>()
        .delete_<resource>(),
)

Step 5: Add i18n Keys

Add to all 4 locale files at packages/api/swiss_ai_hub/api/i18n/translations/api/controllers.{en,de,fr,it}.yml:

<resource>:
  name: "<Resource>s"
  description: "Manage <resource>s"

The api.controllers. prefix in ApiLocaleString.from_i18n_path("api.controllers.<resource>.name") resolves to the file path translations/api/controllers.{locale}.yml — only the <resource>.name part is a key inside the YAML.

Step 6: Scaffold Tests

Create test directory and stub at packages/api/playground/testing/tests/<resource>/test_<resource>_api.py. Follow the patterns in playground/testing/tests/agent/ or playground/testing/tests/role/.

Step 7: Verify

1. Confirm the controller is importable: cd packages/api && uv run python -c "from swiss_ai_hub.api.routes.<resource>.<resource>_controller import <Resource>Controller"
2. Confirm registration in packages/api/app/main.py — the controller must be imported and mounted via runner.mount()
3. Confirm i18n keys exist in all 4 locale files: packages/api/swiss_ai_hub/api/i18n/translations/api/controllers.{en,de,fr,it}.yml
4. Run tests: cd packages/api && make test

Key Conventions

• Controller is thin: Delegates to Service, only handles HTTP concerns
• Annotated for everything: Params, dependencies, auth — all use Annotated
• Docstrings on endpoints: Short description of what the endpoint does
• Locale handler: Always inject t: Annotated[LocaleHandler, Depends(use_locale)]
• Pagination types: Use PageNumber and PageSize type aliases from swiss_ai_hub.api.pagination.type
• Error handling: Let services raise HTTPException -- don't catch in controllers
• Path validation: Use Path(pattern=r"^[a-f0-9]{24}$") for MongoDB ObjectId params

Examples

Input: $ARGUMENTS = "project" Expected output files:

• packages/api/swiss_ai_hub/api/routes/project/project_controller.py with ProjectController(Controller)
• packages/api/swiss_ai_hub/api/routes/project/project_service.py (stub -- use /scaffold-api-service for full service)
• packages/api/swiss_ai_hub/api/routes/project/dto/project_dto.py, create_project_request.py, update_project_request.py, paginated_projects_response.py
• Registration added to packages/api/app/main.py
• i18n keys added to packages/api/swiss_ai_hub/api/i18n/translations/api/controllers.{en,de,fr,it}.yml

Troubleshooting

• 404 on new endpoint: Verify the controller is mounted in main.py and the fluent builder methods are chained
• Permission denied (403): Check the permission template string matches what is configured in the role system (e.g., aihub.user.?> vs aihub.admin.resource)
• Missing tags in Swagger: Ensure tags=self.tags is passed to every router decorator
• i18n key not found: Verify locale YAML files have the correct nested path under api.controllers.<resource>
• Duplicate route conflict: Check that route parameter default values do not clash with existing controllers