A customer-friendly API does not begin with a pretty schema. It begins with respect for how clients live with the contract every day.
In real design work, the chapter shows how request fan-out, payload shape, stable contracts, and the choice between BFF, GraphQL, and REST make an API fit client tasks.
In interviews and engineering discussions, it helps discuss client-oriented facades without drifting into over-customization for one consumer.
Practical value of this chapter
Design in practice
Design APIs from client tasks: fewer request fan-outs, clear payloads, and stable contracts.
Decision quality
Choose BFF, GraphQL, or REST by consumer profile and interface change frequency.
Interview articulation
Show how client pain becomes concrete architecture decisions.
Failure framing
Control over-customization risk when API design drifts toward a single client.
Source
Customer-friendly API
Summary of a talk about client-oriented APIs.
This article grew out of conversations around 2020, when I was explaining to server-side teams that a long list of separate API entry points does not make an API friendly. To assemble one screen, clients sometimes had to call many internal services, which hurt UX and slowed product development.
A customer-friendly API is a facade that returns scenario-ready data to the client instead of forcing the client to assemble a response from many services.
The point of this chapter is not the facade itself, but the API consumer's perspective: how client facades, BFF, payload shape, request fan-out, over-fetching, under-fetching, and contract evolution affect product speed.
Convenient for us ≠ convenient for clients
Server team's view
- The server team sees a set of API entry points and services.
- Clients are expected to fetch what they need and know too much about internals.
- Client-side data composition is treated as normal.
Client's view
- One screen is assembled from several APIs.
- The client has to fan out calls and merge responses.
- Business composition moves into the client application.
Why mobile clients feel this first
Tight coupling
The app depends on the shape, number, and order of API entry points.
Duplicated logic
The same data aggregation is implemented separately for iOS and Android.
Non-core work
Client-side data composition distracts from UI/UX and client logic.
Slow change cycle
Any change in API aggregation requires an app release.
Solution: a client-oriented facade
What the facade does
- One network round trip instead of a fan-out of calls.
- A contract for a screen or scenario, not a generic field set.
- API aggregation moves closer to the server side.
- Contract evolution without a mandatory client release.
Result
The client gets ready-to-use data in one request, while the server side remains the place where business composition and contract evolution live.
Clients
Web / Mobile
Facade
BFF / GraphQL
Services
Microservices
Two facade approaches
BFF (Backend for Frontend)
A server layer for a specific client type: it aggregates data, hides internal complexity, and returns a screen-oriented contract.
GraphQL
The client chooses the response shape within a schema and receives only the fields it needs, as long as the team controls query complexity.
Decision matrix
BFF
controlGraphQL
flexibilityRelative scores: BFF gives more control; GraphQL gives more client freedom.
Control vs freedom
BFF = server-side control
- A contract for a specific interface.
- Latency, caching, and response size are easier to control.
- Less client freedom means fewer accidental risks.
GraphQL = client freedom
- The client shapes requests for the screen.
- Useful for complex interfaces and experimentation.
- Requires query limits, monitoring, and API governance.
Hybrids in practice
- GraphQL can act as a facade over services.
- A BFF can use GraphQL for part of its data access.
- API Gateway covers shared platform concerns; BFF covers client-specific behavior.
Mini checklists
The API is inconvenient for clients
- One screen needs 5-15 requests.
- The client merges responses from different services.
- The data shape changes only through a client release.
- Different clients repeat the same aggregation logic.
- Temporary adapters and workarounds keep growing.
When BFF fits
- Different clients need different payload shapes.
- Mobile releases are expensive and infrequent.
- Microservices create internal request fan-out.
- The UI team needs autonomy and isolated change.
When GraphQL helps
- The UI is complex and has many presentation variants.
- The team wants a self-documenting schema and typed queries.
- The team is ready to invest in query limits, monitoring, and controls.
Conclusion and recommendations
If you need a controlled baseline for making an API client-friendly, BFF often wins: it concentrates the contract, reduces call count, and simplifies client evolution.
Related chapters
- Web API Design: The Missing Link (short summary) - REST design practices for client contracts: URL structure, links, and payload shape for real user scenarios.
- Learning GraphQL (short summary) - A BFF alternative with client-driven data fetching and different trade-offs in control and flexibility.
- API Gateway - An API gateway for routing, authorization, and request limiting that complements a client facade at the platform level.
- Continuous API Management (short summary) - API lifecycle operations: versions, API governance, and contract evolution across multiple teams.
- API Design Patterns (short summary) - Contract design patterns that make client-facing APIs predictable and resilient to change.
- API Security Patterns - Security practices for public and internal APIs: authorization, access policies, and integration risk reduction.
- Inter-service communication patterns - How a client facade aligns with internal service contracts and reduces integration complexity.