Backend for Frontend (BFF): Building Client-Optimised APIs That Scale

Client: Mobile App (limited bandwidth, battery)
Calls: GET /users/123
Response:
{
  "id": 123,
  "firstName": "Alice",
  "lastName": "Smith",
  "email": "alice@example.com",    ← Mobile only shows initials
  "phoneNumber": "+44-xxx-xxxxx",  ← Mobile doesn't use this
  "address": { entire object },    ← Not shown in mobile list view
  "preferences": { 50 fields },   ← Mobile ignores all
  "auditHistory": [ 200 entries ], ← Mobile never shows this
  "billingDetails": { ... },       ← Mobile doesn't handle payments
  "permissions": [...]             ← Mobile checks different permissions
}
Mobile only uses: id, firstName, lastName (3 fields out of 80+)
= 96% data over-fetched every single API call

Client: React Dashboard (high bandwidth, complex UI)
Needs: User + their Orders + Order totals + Recent Activity
Calls needed:
  GET /users/123         → 1st network request
  GET /orders?userId=123 → 2nd network request (after 1st completes)
  GET /activity?userId=123 → 3rd network request
  → 3 sequential round trips on a slow cellular connection = 900ms

BEFORE BFF (client-side aggregation over 5G):
Mobile App → GET /users/123 → User Service      (200ms over 5G)
Mobile App → GET /orders?userId=123 → Orders    (200ms over 5G, must wait for step 1)
Total: 400ms minimum (sequential), all over mobile network

AFTER BFF (server-side aggregation over gigabit LAN):
Mobile App → GET /dashboard → Mobile BFF        (200ms over 5G for 1 round trip)
Mobile BFF → GET /users/123 (parallel)          (5ms internal LAN)
Mobile BFF → GET /orders?userId=123 (parallel)  (5ms internal LAN, concurrent with users)
Mobile BFF merges + shapes response             (1ms)
Total: 200ms + 5ms = 205ms — 2× faster, 1 network round trip

Mobile Team: "We need the user + recent orders merged in one call"
Backend Team: "We'll add it to the roadmap" (3 sprints later...)

Mobile Team: "We need user + orders merged"
Mobile Team: builds /mobile/dashboard endpoint in Mobile BFF (today)

Mobile App → Mobile BFF → API Gateway → Microservices

API Gateway handles: TLS termination, rate limiting, JWT validation, routing
Mobile BFF handles: Aggregation, field filtering, mobile-specific auth flows

// mobile-bff/src/routes/dashboard.ts
import { Router, Request, Response } from 'express';

const router = Router();

// Mobile dashboard: single endpoint aggregates 3 microservice calls
router.get('/dashboard', async (req: Request, res: Response) => {
    const userId = req.user.id; // from JWT middleware
    
    try {
        // Fan out: call multiple services in PARALLEL (not sequential)
        const [user, orders, activity] = await Promise.all([
            userServiceClient.getUser(userId),
            orderServiceClient.getRecentOrders(userId, { limit: 5 }),
            activityServiceClient.getRecentActivity(userId, { limit: 10 }),
        ]);
        
        // Shape response for mobile: only the fields mobile UI needs
        const mobileResponse = {
            // From user service (80 fields → 4 fields for mobile):
            user: {
                id: user.id,
                displayName: `${user.firstName} ${user.lastName[0]}.`,
                avatarUrl: user.profile.avatarUrl,
                tier: user.subscriptionTier,
            },
            // From order service (20 fields per order → 4 fields):
            recentOrders: orders.items.map(order => ({
                id: order.id,
                summary: order.items.map(i => i.productName).join(', '),
                total: formatCurrency(order.totalAmount, order.currency),
                status: order.status,
            })),
            // From activity service:
            unreadNotifications: activity.filter(a => !a.read).length,
        };
        
        res.json(mobileResponse);
    } catch (error) {
        // BFF handles partial failures gracefully:
        if (error.service === 'activity') {
            // Non-critical — return dashboard without activity data:
            const [user, orders] = await Promise.all([...]);
            res.json({ user: shapeUser(user), recentOrders: shapeOrders(orders), unreadNotifications: 0 });
        } else {
            res.status(503).json({ error: 'Service temporarily unavailable' });
        }
    }
});

# Web client queries full user profile:
query {
    user(id: "123") {
        id
        firstName
        lastName
        email
        address { street, city, postcode }
        subscriptionTier
        billingDetails { nextBillingDate, amount }
        recentOrders(limit: 20) { id, status, total, createdAt }
    }
}

# Mobile client queries minimal profile (same API, less data):
query {
    user(id: "123") {
        id
        displayName  # computed field — concatenated by resolver
        avatarUrl
        subscriptionTier
        recentOrders(limit: 5) { id, status, total }
    }
}