Designing Experience APIs and Backends for Frontends: Facades, Microservices, and Custom Payload Strategies

In the Web API space a new trend has emerged: engineers and companies are building proprietary APIs that cater to the specific needs of each consumer, a practice that challenges the ideal of a single, universal API design.

Netflix popularized the concept of experience APIs and ephemeral APIs , creating dedicated APIs for each device type to deliver optimized responses, reduce latency, and isolate development from core backend teams. This approach works at Netflix’s scale but may be impractical for smaller organizations.

Microservice architectures have revived API gateways and facades, allowing multiple front‑facing services to expose tailored APIs. Gateways simplify client calls, enable caching, authentication, rate‑limiting, and edge services such as Zuul, but they also introduce operational complexity and inter‑service latency.

Sam Newman’s Backends for Frontends (BfF) pattern advocates separate backends for Web, iOS, Android, etc., improving client‑specific performance. Companies like SoundCloud use BfF successfully, but teams with limited resources should avoid proliferating too many API variants.

Adopting an API‑first contract approach with definition languages like Swagger (OpenAPI), RAML, or API Blueprint helps preserve contracts, generate client SDKs, create mocks, and produce documentation, reducing the risk of breaking consumer code during refactoring.

Custom payload techniques include distinct endpoints (e.g., /api/mobile/movie vs /api/web/movie ), query parameters ( /api/movie?format=mobile ), field filtering ( /api/movie?fields=title,kind ), and inclusion directives ( /api/movie?includes=actors.name ).

Teams can also define custom media types (e.g., application/vnd.github.v3.full+json ) or use the HTTP Prefer header (RFC 7240) such as Prefer: return=mobile , with corresponding Preference-Applied responses, to let clients request specific profiles.

GraphQL offers the ultimate client‑driven payload control. For example:

{
  user(id: 3500401) {
    id,
    name,
    isViewerFriend,
    profilePicture(size: 50) {
      uri,
      width,
      height
    }
  }
}

which yields a response like:

{
  "user": {
    "id": 3500401,
    "name": "Jing Chen",
    "isViewerFriend": true,
    "profilePicture": {
      "uri": "http://someurl.cdn/pic.jpg",
      "width": 50,
      "height": 50
    }
  }
}

Hypermedia APIs (HATEOAS) can embed links and resources, for instance:

{
  "_links": {
    "self": { "href": "/movie/123" },
    "mobile": { "href": "/m/movie/123" }
  }
}

Formats like Hydra, HAL, and SIREN further support embedded entities, reducing round‑trips for related data.

In summary, while microservices and API facades enable fine‑grained, client‑specific APIs, organizations must balance the benefits against the added cost. Small teams may opt for a single comprehensive API supplemented by a few mobile‑specific variants and lightweight techniques such as field filtering or Prefer headers, whereas larger teams can sustain dedicated BfF services or experience APIs.