A customer-friendly API does not begin with a pretty schema. It begins with respect for how clients have to live with the contract every day.
In real design work, the chapter shows how low fan-out, clear payloads, stable contracts, and an intentional choice between BFF, GraphQL, and REST make an API fit client tasks rather than backend internals.
In interviews and engineering discussions, it helps talk about customer-oriented façades without drifting into over-customization for a single consumer.
Practical value of this chapter
Design in practice
Design APIs from consumer tasks: low fan-out, clear payloads, and stable contracts.
Decision quality
Choose BFF/GraphQL/REST façade by consumer profile and UI change frequency.
Interview articulation
Show how consumer pain maps translate into concrete architecture decisions.
Failure framing
Control over-customization risk when API design drifts toward a single client.
Source
Customer-friendly API
Summary of the report on client-oriented APIs.
This article was born around 2020, when I was explaining to backend teams that “100,500 separate endpoints” do not make an API user-friendly. To assemble one screen, clients sometimes had to pull 50 different handlers, which broke the UX and slowed down the development of the product.
Customer-friendly API is a facade that gives the client a ready-made script payload, rather than forcing him to collect data from many services.
API is convenient for us ≠ convenient for clients
Backend team's view
- There is a set of endpoints and services.
- Clients simply go for data.
- Data composition is considered a front task.
Client's view
- One screen = several different APIs.
- It is necessary to aggregate and glue the answers.
- The business composition ends up on the client.
Why mobile phones especially hurt
Tight coupling
The application is strictly linked to the format and number of APIs.
Duplicating logic
The same data aggregation is implemented separately for iOS and Android.
Non-core work
Composition of data on the front distracts from UI/UX and client logic.
Long cycle of changes
Any change to the aggregation requires the application to be released.
Solution: customer-oriented façade
What does a façade do?
- One call instead of a set of round-trip requests.
- A contract for a specific screen or scenario.
- Data composition is moved closer to the backend.
- API evolution without mandatory client release.
Result
The client receives ready-made data in one request, and the backend remains the place where business composition and contract evolution live.
Clients
Web / Mobile
Facade
BFF / GraphQL
Services
Microservices
Two approaches to the facade
BFF (Backend for Frontend)
Server layer for a specific client: aggregates data and hides complexity.
GraphQL
The client himself sets the form of the response within the framework of the scheme.
Selection Matrix
BFF
controlGraphQL
flexibilityThe ratings are relative: they show where there is more control and where there is more freedom in API management.
Control vs freedom
BFF = server control
- Contract for a specific UI.
- Easier to control performance and cache.
- Less freedom means less risks.
GraphQL = freedom for the client
- The client generates requests for the screen.
- Flexible for complex UIs and experimentation.
- We need restrictions, monitoring and governance.
Hybrids and practice
- GraphQL can be a facade over services.
- BFF can use GraphQL for some of the data.
- API Gateway covers cross-sections, and BFF covers client specifics.
Mini checklists
API is inconvenient for the client
- One screen = 5-15 requests.
- The client merges responses from different services.
- The data format changes only through a client release.
- Different clients have copy-paste aggregations.
- The number of crutches and adapters is growing.
When is the BFF suitable?
- Different clients require different payloads.
- Mobile releases are expensive and rare.
- Microservices provide a lot of downstream calls.
- We need to isolate changes and give autonomy to the UI team.
When is GraphQL useful?
- Complex UI and many presentation options.
- I would like self-documentation and schema typification.
- There is a willingness to invest in restrictions and control of requests.
Conclusion and recommendations
If you want a basic, controlled way to make an API client-friendly, BFF often wins: it concentrates the contract, reduces the number of calls, 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 selection and different trade-offs in control and flexibility.
- API Gateway - An edge layer for routing, auth, and rate limiting that complements a client-oriented facade strategy.
- Continuous API Management (short summary) - Lifecycle operations for API versions, 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, policy enforcement, and integration risk reduction.
- Inter-service communication patterns - How a client facade aligns with internal service contracts and reduces integration complexity.