API Gateway

The API Gateway is a service responsible for routing HTTP requests between the new backend and legacy backend, depending on whether a specific feature gate is enabled. This enables safe, gradual rollouts of new backend functionality while maintaining compatibility with the existing system.

Purpose

This gateway acts as a controlled router between backend systems. It supports:

• Feature-flag-driven backend switching
• Observability through Sentry or console
• Tracing of all requests via OpenTelemetry
• Payload serialization/deserialization for compatibility between backends

Request Routing Logic

Observability Initialization

• If a SENTRY_DSN is present in the environment, Sentry is initialized for error tracking and tracing.
• Otherwise, fallback observability is logged to the console.

Tracing

• Each HTTP request is wrapped in an OpenTelemetry span via startActiveRequestSpan.

Routing Decision

• For each incoming request, the gateway uses shouldTargetNewBackend() to determine whether a feature gate is enabled for the requested route.
• If enabled, the request is forwarded to the new backend (NEW_BACKEND_URL).
• Otherwise, it is routed to the legacy backend (LEGACY_BACKEND_URL).

Payload Serialization & Compatibility

When routing to the new backend, the gateway adapts the request and response payloads to ensure compatibility with the legacy API:

Direction	Transformation	Details
Request → New	snake_case → camelCase	Deserializes the incoming JSON body into the RPC action’s single supported parameter. Only one parameter is allowed, matching the controller action signature.
Response → Client	camelCase → snake_case	Serializes the RPC action’s response object back into snake_case JSON so the legacy consumers receive the expected format.

The RPC controller action supports exactly one parameter. The gateway collects and converts the entire request body into that single parameter object.

Environment Variables

Configuration is loaded and validated using Deepkit. The following environment variables are expected:

Variable	Description	Required
NEW_BACKEND_URL	Base URL of the new backend service to route requests when the feature gate is enabled.	✅
LEGACY_BACKEND_URL	Base URL of the legacy backend system. All fallback/default routing goes here.	✅
STATSIG_SECRET_KEY	Secret key used to evaluate feature flags via Statsig.	✅
STATSIG_STABLE_ID	Stable identifier used in feature flag evaluations. Helps group gateway traffic.	❌ (default: api-gateway)
SENTRY_DSN	Optional Sentry DSN. Enables observability through Sentry. Fallback is console logging.	❌

Environment variables for local development can be found in 1Password.
These should be defined in the project’s .env file.

Observability

• Tracing is automatically applied to every request using OpenTelemetry.
• Sentry integration is conditionally enabled if SENTRY_DSN is provided.
• Console fallback ensures visibility in non-production environments.