Architectural Styles · Lesson 07

Client-adapting APIs

A single backend must serve a terse mobile app on a 3G signal, a data-hungry web dashboard, and a partner integration that wants things its own way — all at the same time. Solving that tension without forking your codebase is what client-adapting APIs are about.

The problem: one shape does not fit all

Imagine a /users/{id} endpoint that returns a full user record: name, email, address, preferences, last-100-login timestamps, billing details, and avatar URL. A native mobile app on a metered data plan needs only the name and avatar. A web dashboard needs everything. A partner integration needs a different subset in a different field-naming convention. If you return the full record to everyone, you are taxing mobile users with bytes they discard and leaking billing fields to clients that should not see them.

Think of it like a newspaper printing run: the core news story is the same regardless of whether it goes to a broadsheet, a tabloid, or a digital summary. The compositor shapes the same content into the right form for the right medium without changing the story itself. Your API needs a compositor layer.

Technique 1 — HTTP content negotiation

HTTP has built-in vocabulary for clients to declare their preferences. The Accept header family lets a client say "I want this media type, this language, and I can handle this encoding." The server then honours the best match it supports and confirms via the response Content-Type header. This is called proactive negotiation (or server-driven negotiation).

Accept — media-type negotiation

A client that can render either JSON or MessagePack (a compact binary format) can list both and assign relative quality with q weights:

GET /v1/reports/2024-Q4 HTTP/1.1
Host: api.example.com
Accept: application/x-msgpack;q=0.9, application/json;q=0.8

# Server responds with the highest-quality format it supports
HTTP/1.1 200 OK
Content-Type: application/json   # server chose JSON; it does not speak msgpack
Vary: Accept                        # tells caches: response differs by Accept

If the server cannot satisfy any listed type it returns 406 Not Acceptable.

Accept-Language — localisation without multiple endpoints

Rather than publishing /en/products and /fr/products as separate routes, a single endpoint reads Accept-Language: fr-CA, fr;q=0.9, en;q=0.8 and returns translated content. The canonical URL is preserved, which matters for cache efficiency.

Accept-Encoding — on-the-wire compression

Every HTTP response can be compressed transparently. A client declares Accept-Encoding: br, gzip (Brotli preferred, gzip fallback). The server compresses and adds Content-Encoding: br to the response. The client decompresses automatically. A 200 KB JSON payload typically shrinks to 15–30 KB under Brotli — an 85% saving that costs a few milliseconds of CPU.

Technique 2 — sparse fieldsets / field selection

Content negotiation handles format, but not which fields. For that, a common pattern is a fields (or select) query parameter that lets the caller enumerate only the fields it needs.

# Mobile app: I only need name and avatar to paint a list row
GET /v1/users/42?fields=id,name,avatar_url

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "name": "Priya Sharma",
  "avatar_url": "https://cdn.example.com/avatars/42.webp"
}

# Web dashboard: give me everything
GET /v1/users/42   # no fields param → full record

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "name": "Priya Sharma",
  "avatar_url": "https://cdn.example.com/avatars/42.webp",
  "email": "priya@example.com",
  "address": { "city": "Bangalore", "country": "IN" },
  "billing_tier": "pro",
  "created_at": "2023-01-12T08:00:00Z"
}

Google's JSON API style guide calls this concept partial responses and uses the same fields parameter across its APIs. The server fetches or computes only the needed sub-tree, which can meaningfully reduce both network bytes and database reads when done at the query layer.

Technique 3 — the Backend-for-Frontend (BFF) pattern

Sometimes the adaptation required is too complex for a query parameter. A mobile home screen might need data stitched from three microservices, flattened into a single payload, with mobile-specific field names. A generic API cannot absorb that complexity without becoming a mess of special cases.

The Backend-for-Frontend (BFF) pattern solves this by introducing a thin server-side layer — one BFF per client type — that speaks the core APIs but translates, aggregates, and reshapes responses for its specific client. The BFF lives on the server (fast network to microservices, no CORS issues) and exposes a narrow surface tuned to exactly what its client needs.

This pattern is closely related to the API gateway (covered in rel-04): a gateway handles cross-cutting concerns like auth and rate limiting; a BFF handles client-specific composition. They can coexist or be merged.

Per-client versioning

When a native mobile app ships a new version, old installs remain in the wild for months. A BFF lets you version the client-facing surface independently: v2 of the mobile BFF can consume a new microservice field without forcing the web BFF or partners to change. This is far cheaper than global API versioning (covered in rel-01) because the blast radius of each change is bounded to one client type.

Under the hood: content negotiation on the wire

Content negotiation looks simple from the outside — client says what it wants, server picks. Under the hood it is a precise algorithm that runs on every request and has subtleties that affect caching and correctness.

The full negotiation exchange, header by header

// Client request — declares all preferences in one shot
GET /v1/reports/2024-Q4 HTTP/1.1
Host: api.example.com
Accept: application/json;q=1.0, application/x-msgpack;q=0.9, */*;q=0.1
Accept-Language: fr-CA;q=1.0, fr;q=0.9, en;q=0.7
Accept-Encoding: br;q=1.0, gzip;q=0.9, identity;q=0.5

// Server selection algorithm (per RFC 7231 §5.3):
//   1. For each Accept dimension, filter to types the server can produce.
//   2. Within those, pick the one with the highest q value.
//   3. If q is equal, prefer the more specific type (application/json > */*)
//   4. If nothing matches any listed type → 406 Not Acceptable

// Server supports: JSON only / French and English / gzip only
// Selection:
//   Content-Type: application/json (q=1.0 — only match server has)
//   Content-Language: fr (q=0.9 — fr-CA not available, fr is the next best)
//   Content-Encoding: gzip (q=0.9 — br not available, gzip next best)

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Language: fr
Content-Encoding: gzip
Vary: Accept, Accept-Language, Accept-Encoding
                                 ^--- CRITICAL: tells every cache these three headers
                                      change the response body; cache separately for each
                                      combination — a French gzip and an English plain
                                      response must not share a cache slot

The Vary header is not optional decoration. Without it a CDN will cache the first response it sees and serve it to all subsequent clients, regardless of their Accept-Language or Accept-Encoding. A French-speaking user would receive cached English content; a client that cannot decompress brotli would receive cached brotli bytes. The Vary header turns the cache key from just the URL into URL + Accept + Accept-Language + Accept-Encoding.

Sparse fieldset request — how the server parses and applies it

The ?fields= parameter is a server-side convention, not an HTTP standard — so the server must implement the parsing. Here is the typical implementation pattern and its edge cases:

// Request
GET /v1/users/42?fields=id,name,address.city,preferences.theme

// Server parse step — split on comma, build a field allowlist
allowed = {"id", "name", "address.city", "preferences.theme"}

// Server apply step — walk the serialised object, keep only allowed paths
// Full object in the database:
{
  "id": 42,                          // ✓ in allowlist
  "name": "Priya Sharma",            // ✓ in allowlist
  "email": "priya@example.com",      // ✗ omitted
  "address": {
    "city": "Bangalore",             // ✓ via "address.city"
    "country": "IN",                // ✗ "address.country" not in list
    "postcode": "560001"            // ✗ omitted
  },
  "preferences": {
    "theme": "dark",               // ✓ via "preferences.theme"
    "notifications": true          // ✗ omitted
  },
  "billing_tier": "pro"             // ✗ omitted
}

// Response body after field filter applied
{
  "id": 42,
  "name": "Priya Sharma",
  "address": { "city": "Bangalore" },
  "preferences": { "theme": "dark" }
}

Three important implementation details: (1) if the database query selects all columns then applies the filter in the serialiser, the database reads are unchanged — the savings are only in network bytes and deserialization time. For real savings, push the field list into the SELECT clause or projection. (2) Nested paths like address.city mean the parent key address must still appear in the output (as an object) even though address.country is omitted. (3) A request for a field that doesn't exist should be silently ignored — not a 400 — to keep clients decoupled from schema evolution.

The full wire exchange for a negotiated sparse-fieldset request

How to debug & inspect it

Content negotiation and sparse fieldset bugs are often invisible — the server returns 200, the client gets data, but it is the wrong data, the wrong language, or a bloated payload. The fix requires inspecting the exact headers exchanged.

Testing Accept variants with curl

Debug checklist:

1. Use curl -v to see both request headers you sent and response headers you received — look for Content-Type, Content-Language, Content-Encoding, and Vary.
2. Check Vary on every response that varies by a request header — missing Vary is a silent cache-poisoning bug.
3. Test sparse fieldsets by requesting exactly two fields and confirming with python3 -m json.tool that no extra fields appear.
4. Test 406 behaviour: send an Accept header for a format you know the server doesn't support — it should return 406, not a 200 with the wrong content type.
5. Run two requests with different Accept-Language values, then a third with the first language again — the third should hit the CDN cache (x-cache: HIT, Age: >0) while the second with the new language was a MISS.

# Mobile: minimal list row
GET /v1/feed?fields=id,author_name,author_avatar,body,like_count,comment_count

# Web: everything except sensitive ML field (default — no fields param)
GET /v1/feed

# Internal analytics: all fields including ML signals (scoped API key required)
GET /v1/feed?fields=*,raw_ml_signals
Authorization: Bearer INTERNAL_KEY_abc

Sources & further reading

• MDN — HTTP Content Negotiation
• Google API Design Guide — Partial Responses
• Sam Newman — Backend for Frontend pattern
• RFC 7231 §5.3 — Content Negotiation
• MDN — Vary header
• MDN — Accept header