Reference documentation for the BFF service architecture, client adapters, error handling, and rate limiting.
Overview#
The BFF (Backend for Frontend) service provides:
- Request Routing: Multi-region service discovery with retry logic
- Response Aggregation: Parallel/sequential multi-service requests
- Response Shaping: Client-specific payload optimization
- Circuit Breaker: Graceful degradation with mock fallbacks
- Error Normalization: Consistent error format with correlation IDs
Service Request Routing#
Configuration#
Service registry defines backend service configurations:
interface ServiceConfig {
url: string; // Primary service URL
timeout?: number; // Request timeout (default: 30000ms)
retries?: number; // Retry attempts (default: 0)
retryDelayMs?: number; // Base retry delay (default: 150ms)
regionalUrls?: Record<string, string>; // Region-specific URLs
defaultRegionId?: string; // Default region
}
Multi-Region Support#
Requests are routed to the appropriate regional endpoint:
// Region resolution priority:
// 1. x-region-id or x-preferred-region-id header
// 2. Service defaultRegionId
// 3. First active region
Region Configuration:
interface Region {
region_id: string;
region_name: string;
endpoint: string;
availability_zones: string[];
status: 'active' | 'degraded' | 'inactive';
}
Request Flow#
Client Request
↓
Check Circuit Breaker State
↓
Resolve Regional URL
↓
Add Headers (correlation, trace, span)
↓
Execute Request with Timeout
↓
├─ Success → Record Success → Return Response
│
└─ Failure → Retry with Backoff → Record Failure
↓
Mock Fallback Response
Tracing Headers#
All requests include distributed tracing headers:
| Header | Description |
|---|---|
x-correlation-id |
Request correlation ID (inherited or generated) |
x-trace-id |
Trace ID for distributed tracing |
x-span-id |
Current span ID (16 chars) |
x-parent-span-id |
Parent span ID |
x-service-name |
Service name (bff) |
x-service-version |
Service version |
Response Aggregation#
Combine multiple service requests in a single API call.
Aggregation Endpoint#
POST /v1/aggregate
Content-Type: application/json
Authorization: Bearer <token>
{
"strategy": "parallel",
"requests": [
{
"id": "user_profile",
"service": "auth",
"path": "/v1/users/me",
"method": "GET"
},
{
"id": "content_feed",
"service": "content",
"path": "/v1/feed",
"method": "GET"
},
{
"id": "notifications",
"service": "notification",
"path": "/v1/notifications",
"method": "GET",
"headers": { "x-limit": "10" }
}
]
}
Aggregation Strategies#
| Strategy | Description |
|---|---|
parallel |
Execute all requests concurrently (default) |
sequential |
Execute requests in order |
Response Format#
{
"results": [
{
"id": "user_profile",
"success": true,
"data": { "user_id": "...", "name": "..." },
"latency": 45
},
{
"id": "content_feed",
"success": true,
"data": { "items": [...] },
"latency": 120
},
{
"id": "notifications",
"success": false,
"error": "Service unavailable",
"latency": 30000
}
],
"totalLatency": 120,
"strategy": "parallel"
}
Client-Specific Response Shaping#
Optimize responses based on client type and capabilities.
Client Types#
| Client Type | Detection | Optimizations |
|---|---|---|
web |
Default | Full payload |
mobile |
mobile, android, iphone in UA |
Image optimization, lightweight items, 500KB limit |
tablet |
tablet, ipad in UA |
Medium-res images |
embedded |
embedded, iot in UA |
Minimal essential fields only |
Configuration#
interface ResponseShapingConfig {
clientType?: 'web' | 'mobile' | 'tablet' | 'embedded';
apiVersion?: string;
features?: string[];
maxPayloadSize?: number;
compressionLevel?: 'low' | 'medium' | 'high';
includeMetadata?: boolean;
}
Mobile Optimizations#
// Image URLs transformed
img.url.replace('/original/', '/mobile/');
img.thumbnail = img.url.replace('/original/', '/thumb/');
// List items stripped of heavy content
const { full_content, raw_data, ...lightweight } = item;
// Numbers reduced to 2 decimal places
metrics[key] = Number(value.toFixed(2));
Embedded/IoT Optimizations#
Only critical fields are returned:
const criticalFields = ['id', 'status', 'value', 'timestamp', 'error'];
Payload Size Limits#
When payload exceeds limit, fields are removed in priority order:
raw_datafull_contentdebug_infometadatainternal_notesrelated_items
Then arrays are truncated to 50%.
Response Metadata#
When includeMetadata: true:
{
"data": "...",
"_meta": {
"client_type": "mobile",
"api_version": "v1",
"shaped": true,
"timestamp": "2025-01-15T10:30:00.000Z"
}
}
Headers for Client Detection#
| Header | Description |
|---|---|
User-Agent |
Client type detection |
X-API-Version |
API version (default: v1) |
X-Features |
Comma-separated feature flags |
Enable Debug Metadata#
GET /v1/endpoint?debug=true
Circuit Breaker Pattern#
Graceful degradation when services fail.
Circuit Breaker States#
| State | Description |
|---|---|
closed |
Normal operation, requests pass through |
open |
Service failed, reject requests immediately |
half-open |
Testing recovery, limited requests |
State Transitions#
CLOSED → OPEN (after 5 failures)
↓
OPEN (30 second cooldown)
↓
HALF-OPEN (test requests)
↓
├─ 3 successes → CLOSED
│
└─ Any failure → OPEN
Configuration#
// Failure threshold to open circuit
const FAILURE_THRESHOLD = 5;
// Cooldown before half-open state
const COOLDOWN_MS = 30000;
// Successes needed to close circuit
const SUCCESS_THRESHOLD = 3;
Mock Fallback Responses#
When circuit is open, mock fallback responses are returned:
{
"status": 200,
"body": { "mock": true, "data": [] },
"fallback": true,
"trace_id": "abc123",
"error": "Circuit breaker is open for service auth"
}
Circuit Breaker API#
GET /v1/admin/circuit-breakers
Returns state of all circuit breakers.
Error Handling#
Consistent error normalization with correlation tracking.
Error Response Format#
{
"error": "Authentication failed",
"code": "auth.invalid_credentials",
"category": "authentication",
"severity": "error",
"http_status": 401,
"trace_id": "abc123-def456",
"correlation_id": "xyz789",
"service": "bff",
"timestamp": "2025-01-15T10:30:00.000Z",
"retry_after": 60
}
Error Headers#
| Header | Description |
|---|---|
x-correlation-id |
Request correlation ID |
x-error-category |
Error category |
x-error-severity |
Error severity level |
retry-after |
Seconds until retry (for rate limits) |
Error Categories#
| Category | HTTP Status | Description |
|---|---|---|
validation |
400 | Invalid request data |
authentication |
401 | Auth failure |
authorization |
403 | Permission denied |
not_found |
404 | Resource not found |
rate_limit |
429 | Too many requests |
service_unavailable |
503 | Backend service down |
network_error |
502 | Network/timeout error |
internal |
500 | Internal error |
Error Management API#
Get Error Mappings:
GET /v1/admin/errors/mappings
Test Error Normalization:
POST /v1/admin/errors/normalize
Content-Type: application/json
{
"error": {
"message": "Custom error",
"code": "custom_error"
},
"context": {
"service": "content"
}
}
Simulate Error Types:
POST /v1/admin/errors/test
Content-Type: application/json
{
"error_type": "rate_limit",
"simulate_service": "auth"
}
Available error types:
validationauthenticationrate_limitservice_unavailablenetwork_timeoutinternal
Rate Limiting#
Rate limiting via circuit breaker pattern and graceful degradation.
Implementation#
Rate limiting is implemented through:
- Circuit Breaker: Protects against cascading failures
- Timeout Enforcement: Per-service configurable timeouts
- Retry Limiting: Maximum retry attempts with exponential backoff
Per-Service Limits#
const serviceConfig = {
timeout: 30000, // 30 second timeout
retries: 2, // 2 retry attempts
retryDelayMs: 150, // Base delay (doubles each retry)
};
Backoff Strategy#
Exponential backoff with maximum cap:
const backoff = retryDelayBase * Math.pow(2, attempt - 1);
const delay = Math.min(backoff, 2000); // Max 2 second delay
Rate Limit Response#
When rate limited by backend:
{
"error": "Rate limit exceeded",
"code": "rate_limit_exceeded",
"retry_after": 60,
"trace_id": "abc123"
}
Headers#
| Header | Description |
|---|---|
Retry-After |
Seconds until rate limit resets |
X-RateLimit-Limit |
Request limit |
X-RateLimit-Remaining |
Remaining requests |
X-RateLimit-Reset |
Reset timestamp |
Multi-Region Configuration#
Register Region#
registerRegion({
region_id: 'us-east-1',
region_name: 'US East',
endpoint: 'https://api-east.example.com',
availability_zones: ['us-east-1a', 'us-east-1b'],
status: 'active',
});
Update Region Status#
updateRegionStatus('us-east-1', 'degraded');
Set Region Priority#
setRegionPriority('us-east-1', 1); // Highest priority
setRegionPriority('us-west-2', 2);
Get Configuration#
const config = getMultiRegionConfig();
// {
// regions: [...],
// active_regions_count: 2,
// total_availability_zones: 6,
// is_active_active: true,
// priorities: [{ region_id: 'us-east-1', priority: 1 }, ...],
// last_updated: "2025-01-15T10:30:00.000Z"
// }
Active-Active Requirements#
Active-active mode requires at least 2 active regions.
Integration Example#
import { createServiceRequest } from './setup/create-service-request';
import { initializeCircuitBreakers } from './utils/circuit-breaker';
// Initialize
const serviceRegistry = {
auth: { url: 'http://auth:8080', timeout: 5000, retries: 2 },
content: { url: 'http://content:8080', timeout: 10000 },
notification: { url: 'http://notification:8080' },
};
const circuitBreakers = initializeCircuitBreakers(serviceRegistry);
const makeRequest = createServiceRequest({
serviceRegistry,
circuitBreakers,
recordCircuitBreakerSuccess,
recordCircuitBreakerFailure,
getMockFallbackResponse,
delay: (ms) => new Promise((r) => setTimeout(r, ms)),
randomUUID: () => crypto.randomUUID(),
});
// Make service request
const response = await makeRequest('auth', '/v1/users/me', 'GET', {
Authorization: 'Bearer token',
});
if (response.fallback) {
console.log('Using fallback response');
}
Related Documentation#
- Error Codes - Complete error code reference
- API Versioning - Version management
- Authentication - Auth patterns