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.