using-archipy-services

Using ArchiPy Services

Services are thin transport adapters (HTTP routers / gRPC servicers). Bootstrap often lives in manage.py — follow this rule there too.

Live: https://syntaxarc.github.io/ArchiPy/getting-started/project_structure/

Responsibilities

• Validate and translate HTTP/gRPC requests into domain *InputDTO.
• Call the appropriate logic class; return domain *OutputDTO.
• Let AppUtils exception handlers/interceptors map ArchiPy BaseError status metadata. Add transport-specific mapping only when the domain error has no suitable mapping; never expose internal exception text.
• Version in path: services/{domain}/v{n}/ — not in business logic.

REST resource paths (FastAPI)

Paths are hierarchical resources: /api/v{n}/<collection>/{<resource>_uuid}/<child-collection>/{<child>_uuid}/...

/api/v1/users/{user_uuid}/campaigns/{campaign_uuid}/ad-groups/{ad_group_uuid}/ad-items/{ad_item_uuid}

• kebab-case for every literal segment (ad-groups, ad-items) — never snake_case, camelCase, or PascalCase.
• Plural nouns for collections; the HTTP method is the verb, so no /get-user or /createCampaign. Use a sub-resource or a kebab-case action segment only when no CRUD verb fits (POST .../campaigns/{campaign_uuid}/pause).
• Nesting expresses ownership: a child id is only meaningful under its parent, and the logic must verify the parent owns the child instead of trusting the URL.
• Path parameters are snake_case Python names typed UUID (user_uuid: UUID), so FastAPI validates them; keep the placeholder name identical at every level ({campaign_uuid}, not {id}).
• Version prefix /api/v{n} comes from the router (APIRouter(prefix="/api/v1")), one version per services/{domain}/v{n}/. Do not repeat the version in child routes.
• Collection root has no trailing slash (/api/v1/users); do not mix trailing-slash styles.

Actor identity and audit columns (JWT auth)

With any JWT-based auth (fastapi_auth / grpc_auth from archipy.adapters.keycloak.auth, JWTUtils, or another issuer) the acting principal comes from the verified access token, never from a path parameter. With the Keycloak guards it is an AuthenticatedUserDTO, also readable anywhere below the endpoint through AuthContextManager (do not read request.state.user_info and friends; they warn and go away in 6.0.0); for other JWTs read the claims the same way: actor = act.sub (RFC 8693 delegation/impersonation) when present, else sub.