presentation.routers.api.v1.users

src.presentation.routers.api.v1.users

Users resource handlers.

Handler functions for user management endpoints. Routes are registered via ROUTE_REGISTRY in routes/registry.py.

Handlers

create_user - Create new user (registration)

Classes

Functions

create_user async

create_user(
    request: Request,
    data: UserCreateRequest,
    handler: RegisterUserHandler = Depends(
        handler_factory(RegisterUserHandler)
    ),
) -> UserCreateResponse | JSONResponse

Create a new user (registration).

POST /api/v1/users → 201 Created

Creates a new user account and sends a verification email. User must verify email before creating a session (login).

Parameters:

Name	Type	Description	Default
request	Request	FastAPI request object.	required
data	UserCreateRequest	User creation request data (email, password).	required
handler	RegisterUserHandler	Registration handler (injected).	Depends(handler_factory(RegisterUserHandler))

Returns:

Type	Description
UserCreateResponse | JSONResponse	UserCreateResponse on success (201 Created).
UserCreateResponse | JSONResponse	JSONResponse with error on failure (400/409).

Source code in src/presentation/routers/api/v1/users.py

async def create_user(
    request: Request,
    data: UserCreateRequest,
    handler: RegisterUserHandler = Depends(handler_factory(RegisterUserHandler)),
) -> UserCreateResponse | JSONResponse:
    """Create a new user (registration).

    POST /api/v1/users → 201 Created

    Creates a new user account and sends a verification email.
    User must verify email before creating a session (login).

    Args:
        request: FastAPI request object.
        data: User creation request data (email, password).
        handler: Registration handler (injected).

    Returns:
        UserCreateResponse on success (201 Created).
        JSONResponse with error on failure (400/409).
    """
    # Create command from request data
    command = RegisterUser(
        email=data.email,
        password=data.password,
    )

    # Execute handler
    result = await handler.handle(command, request)

    # Handle result
    match result:
        case Success(value=user_id):
            return UserCreateResponse(
                id=user_id,
                email=data.email,
            )
        case Failure(error=error):
            # Map error to ApplicationErrorCode
            if "already registered" in error.lower():
                error_code = ApplicationErrorCode.CONFLICT
            else:
                error_code = ApplicationErrorCode.COMMAND_VALIDATION_FAILED

            app_error = ApplicationError(
                code=error_code,
                message=error,
            )
            return ErrorResponseBuilder.from_application_error(
                error=app_error,
                request=request,
                trace_id=get_trace_id() or "",
            )