API and Security

Explore the API contract and security model.

The BFF documents its real React-facing API through Springdoc OpenAPI and protects runtime endpoints with JWT Resource Server security.

Swagger UI

Swagger UI is available when documentation is enabled. The local profile enables it automatically:

http://localhost:8080/swagger-ui.html

Use the Authorize button with the local JWT token, then call GET /api/dashboard.

Published API docs

The Pages-hosted Swagger UI is a read-only contract viewer generated from Springdoc assets during CI. GitHub Pages cannot run the BFF; use the local UI for authenticated requests.

Open Published Swagger UI OpenAPI JSON OpenAPI YAML

OpenAPI JSON and YAML

Local endpoints:

http://localhost:8080/v3/api-docs
http://localhost:8080/v3/api-docs.yaml

Manual export:

New-Item -ItemType Directory -Force -Path target\openapi | Out-Null
Invoke-WebRequest -UseBasicParsing http://localhost:8080/v3/api-docs -OutFile target\openapi\openapi.json
Invoke-WebRequest -UseBasicParsing http://localhost:8080/v3/api-docs.yaml -OutFile target\openapi\openapi.yaml

Generated OpenAPI files belong under target or CI artifacts, not source control.

Security Behavior

/api/** requires a valid JWT.
/actuator/health and /actuator/health/** are public.
All other routes are denied by default.
Authentication and access-denied failures return structured JSON ApiError payloads.
OpenAPI JSON/YAML and Swagger UI are disabled by default and enabled intentionally in the local profile.

JWT decoder precedence is JWK set URI, then issuer URI, then local HMAC secret.

Resilience and Fallback Behavior

User service failure returns a safe Guest User profile for the authenticated subject.
Product service failure returns an empty recommendation list.
Circuit breakers are registered with Actuator health.
The frontend receives a stable dashboard response shape even when downstream services fail.

Configuration

Variable	Purpose	Default
`SERVER_PORT`	BFF HTTP port	`8080`
`USER_SERVICE_BASE_URL`	User service base URL	`http://localhost:8081`
`PRODUCT_SERVICE_BASE_URL`	Product service base URL	`http://localhost:8082`
`USER_SERVICE_TIMEOUT`	User service timeout	`2s`
`PRODUCT_SERVICE_TIMEOUT`	Product service timeout	`2s`
`BFF_JWT_JWK_SET_URI`	JWK set URL for production-style JWT validation	empty
`BFF_JWT_ISSUER_URI`	OIDC issuer discovery URL for production-style JWT validation	empty
`BFF_JWT_SECRET`	HS256 secret when no JWK or issuer URI is supplied	empty; the `local` profile supplies a development-only value
`BFF_JWT_ISSUER`	Optional expected JWT issuer	empty; the `local` profile uses `react-bff-gateway-local`
`BFF_JWT_AUDIENCE`	Expected JWT audience	`react-dashboard`
`SPRINGDOC_API_DOCS_ENABLED`	Enables OpenAPI JSON/YAML endpoints	`false`, enabled by `local`
`SPRINGDOC_SWAGGER_UI_ENABLED`	Enables Springdoc Swagger UI	`false`, enabled by `local`