API reference (OpenAPI / Redoc)¶
The backend serves its own OpenAPI specs and renders them as Redoc pages. Each API
exposes three routes under its versioned base path (/v1):
| Route | Serves |
|---|---|
…/v1/openapi |
Redoc documentation UI |
…/v1/openapi.yaml |
Raw OpenAPI spec (YAML) |
…/v1/postman-collection.json |
Postman collection download |
There are three APIs, each with its own spec:
| API | Service base | Spec source |
|---|---|---|
| Legacy API | /api/v1 |
hand-maintained |
| Member BFF | /bff/v1 |
hand-maintained |
| Clinical BFF | /bff_clinical/v1 |
generated — openapi.generated.yaml |
These routes require auth
All three routes sit behind authOpenApiMiddleware, so opening them in a browser
needs valid credentials — they are not public. This is also why the docs site itself
only links to them rather than embedding them.
Production¶
- Clinical BFF: https://europe-west2-perci-platform-prod.cloudfunctions.net/bff_clinical/v1/openapi
- Member BFF: https://europe-west2-perci-platform-prod.cloudfunctions.net/bff/v1/openapi
- Legacy API: https://europe-west2-perci-platform-prod.cloudfunctions.net/api/v1/openapi
Staging¶
- Clinical BFF: https://europe-west2-perci-platform-staging.cloudfunctions.net/bff_clinical/v1/openapi
- Member BFF: https://europe-west2-perci-platform-staging.cloudfunctions.net/bff/v1/openapi
- Legacy API: https://europe-west2-perci-platform-staging.cloudfunctions.net/api/v1/openapi
CONFIRM — canonical hosts
The hosts above follow the Cloud Functions pattern in the Terraform
cloud_functions_url variable. If a custom domain or a Cloud Run service is the
canonical front door for any environment, replace the relevant URLs here.
Preview deployments¶
Each preview PR gets a Cloud Run URL of the form
https://backend-preview-pr-<n>-<hash>.europe-west2.run.app. The Redoc pages are at the
same paths, e.g. …run.app/bff_clinical/v1/openapi. See
Preview environments and
Cloud Run quick start.
Local¶
With the emulators running (pnpm run dev, see Running locally),
the same paths are served from the local functions/Cloud Run host.
Using the generated client¶
Prefer the generated, typed client over hand-written paths. The Clinical BFF spec above
drives the Flutter client at lib/backend/openapi/ (TypedBffClinicalClient). If an
endpoint is missing from the client, regenerate it from the spec rather than hand-rolling
the path — see the new architecture guide.