Skip to content

4.3 API Gateway

Sprint: Sprint 04 - Platform Infrastructure Services
Feature ID: 4.3
Subtasks: 4.3.1, 4.3.2, 4.3.3, 4.3.4, 4.3.5, 4.3.6

Objective

Deliver "API Gateway" within Sprint 04 - Platform Infrastructure Services.

Dependencies

Aggregated from the subtasks below (prerequisite task IDs and enablers):

  • 4.2.1
  • 4.3.1
  • 4.3.2
  • 4.3.3
  • Sprint 01 Redis (1.3.4)

Subtasks

4.3.1 Gateway application and routing

  • ID: 4.3.1
  • Title: Implement API gateway (8080) with discovery-based routing
  • Description: Create microservices/api-gateway (Spring Cloud Gateway) routing /api/v1/** to domain services by discovery service id (identity, customer, product-catalog, order, subscription, usage, billing, payment, notification, ticket). Centralize per-route path config.
  • Business Purpose: Single external entry point for all client traffic (analysis Section 13).
  • Inputs: analysis Sections 7.2, 13; ADR-005.
  • Outputs: api-gateway app with route definitions, Dockerfile.
  • Acceptance Criteria:
  • A request to /api/v1/customers/** routes to customer-service via discovery (verified against a stub/registered service).
  • Dependencies: 4.2.1
  • Complexity: M

4.3.2 JWT validation filter

  • ID: 4.3.2
  • Title: Implement gateway JWT validation global filter
  • Description: Global filter validating the Keycloak-issued Bearer JWT on every request against the realm JWKS, rejecting missing/invalid/expired tokens with ApiResult.failure (401). Allowlist the Keycloak OIDC endpoints (/realms/telco-crm/protocol/openid-connect/**) and actuator health. Keycloak issues tokens (ADR-011); the gateway only validates. See docs/architecture/keycloak-and-auth.md (FR-IAM-02).
  • Business Purpose: Enforce authentication at the edge so services trust the gateway (NFR-05).
  • Inputs: ADR-011, FR-IAM-02, docs/architecture/keycloak-and-auth.md.
  • Outputs: JWKS-based JWT validation filter + allowlist config.
  • Acceptance Criteria:
  • A request without a token to a protected route returns 401 ApiResult.failure; a valid Keycloak-issued token passes; the Keycloak token endpoint is reachable unauthenticated.
  • Dependencies: 4.3.1
  • Complexity: M

4.3.3 Identity header propagation

  • ID: 4.3.3
  • Title: Propagate X-User-Id and X-User-Roles downstream
  • Description: After JWT validation, extract userId and roles from claims and inject X-User-Id and X-User-Roles headers on the downstream request; strip any client-supplied values to prevent spoofing (FR-IAM-03).
  • Business Purpose: Gateway-behind-trust identity propagation consumed by starter-security (NFR-05).
  • Inputs: FR-IAM-03, PLATFORM-SPEC Section 9.3.
  • Outputs: Header-propagation filter.
  • Acceptance Criteria:
  • Downstream receives X-User-Id/X-User-Roles derived from the token; client-supplied identity headers are overwritten, not trusted.
  • Dependencies: 4.3.2
  • Complexity: M

4.3.4 CorrelationId injection

  • ID: 4.3.4
  • Title: Inject X-Correlation-Id at the gateway
  • Description: Generate X-Correlation-Id when absent and propagate it downstream and back to the client; align with starter-observability's CorrelationFilter key (NFR-13).
  • Business Purpose: End-to-end request correlation across all services (NFR-13).
  • Inputs: analysis Section 12, PLATFORM-SPEC Section 9.6.
  • Outputs: Correlation-injection filter.
  • Acceptance Criteria:
  • Every routed request carries an X-Correlation-Id; an inbound value is preserved, an absent one is generated and echoed on the response.
  • Dependencies: 4.3.1
  • Complexity: S

4.3.5 Redis-backed rate limiting

  • ID: 4.3.5
  • Title: Implement per-user rate limiting (100 req/min)
  • Description: Configure the gateway Redis rate limiter keyed by X-User-Id (fallback to client IP for unauthenticated routes), default 100 req/min, returning 429 with ApiResult.failure when exceeded (NFR-18).
  • Business Purpose: Protect downstream services from abuse and overload (NFR-18).
  • Inputs: analysis Section 13, NFR-18.
  • Outputs: Rate-limiter filter + config.
  • Acceptance Criteria:
  • Exceeding 100 req/min for a user yields 429 ApiResult.failure; the limit resets per window; counters are stored in Redis.
  • Dependencies: 4.3.3, Sprint 01 Redis (1.3.4)
  • Complexity: M

4.3.6 Gateway OpenAPI aggregation

  • ID: 4.3.6
  • Title: Aggregate per-service Swagger UIs at the gateway
  • Description: Configure Springdoc aggregation so each service's OpenAPI is reachable through the gateway under a documented path (ARC-08).
  • Business Purpose: Single discovery point for all API documentation.
  • Inputs: ADR-015, ARC-08.
  • Outputs: Gateway OpenAPI aggregation config.
  • Acceptance Criteria:
  • The gateway Swagger UI lists and loads each registered service's API definition.
  • Dependencies: 4.3.1
  • Complexity: S

Acceptance Criteria

Each subtask above carries its own objective, testable acceptance criteria. This feature is complete when every subtask's acceptance criteria are met.

Deliverables

  • api-gateway app with route definitions, Dockerfile.
  • JWT validation filter + allowlist config.
  • Header-propagation filter.
  • Correlation-injection filter.
  • Rate-limiter filter + config.
  • Gateway OpenAPI aggregation config.

Definition of Done

  • All subtasks (4.3.1, 4.3.2, 4.3.3, 4.3.4, 4.3.5, 4.3.6) completed and their acceptance criteria verified.
  • All listed dependencies satisfied.
  • Build and tests green per the global conventions in ../README.md (Section 3).