API Design for Ten‑Million QPS: From Generic to Specialized, BFF vs GraphQL

Why Generic APIs Were Attractive

In the early stage of a system with a small team and only a few callers (App and PC), the getItemDetail endpoint was designed to return all product‑related data—basic info, price, inventory, promotions, store info, reviews, recommendations, Q&A—in a single large object. This "one‑size‑fits‑all" approach minimized duplicate development and allowed any new client to reuse the same interface without additional work.

The benefit was concrete: a single code path covered all call‑sites, reducing development cost and enabling rapid iteration when resources were limited.

Costs at Ten‑Million QPS

Over‑fetching : Most callers need only a subset of the thirty‑plus fields. For example, the App front‑page requires only price and inventory, yet it still receives reviews, recommendations, and other data. Each extra kilobyte multiplied by ten million requests creates a massive bandwidth burden.

Downstream amplification : The generic endpoint concurrently queries eight or nine downstream services for every call, even when the caller only wants the price. This forces services such as review and recommendation to handle traffic they would otherwise avoid, creating hidden load spikes.

Cache inefficiency : Because the request parameters vary widely across callers, cache hit rates drop dramatically. A monolithic response is either too large to cache effectively or results in an explosion of field‑combination keys, rendering the cache almost useless.

Coupling and change cost : Any new requirement from any client forces a change to the shared endpoint, which then risks breaking other callers. Over time the endpoint becomes a fragile "fossil" that no one dares to modify.

What Specialized APIs Look Like

Per‑endpoint tailoring : Each client gets its own interface that returns only the fields it truly needs. The App front‑page API returns just price and inventory, while the merchant‑backend API returns the full data set.

Per‑scenario aggregation : For high‑frequency scenarios (e.g., product detail front‑page), a dedicated aggregation API bundles price, inventory, and main image, enabling aggressive caching. Low‑frequency or personalized data (reviews, recommendations) are exposed via separate endpoints that can be loaded asynchronously.

Read/write separation : Read‑heavy interfaces are optimized for low latency and high cache hit rates, while write interfaces focus on strong consistency. Splitting them removes conflicting performance goals.

Implementing Specialization with BFF

The Backend‑For‑Frontend (BFF) pattern introduces an adaptation layer between business services and each client. Each client (App, PC, merchant backend) has its own BFF that knows the exact shape required, calls the necessary domain services, performs field‑level trimming, aggregation, and caching, then returns a tailored response.

Benefits include isolating volatile front‑end requirements in the BFF, keeping core business services stable and generic, and allowing independent caching strategies per client. The trade‑off is an extra network hop, additional deployment and operational overhead, and a potential new failure point—acceptable only when client differences are significant.

Is GraphQL a Better Answer?

GraphQL lets callers specify exactly which fields they need, eliminating over‑fetching at the API level. This flexibility shines in environments with many third‑party consumers and highly fragmented field requirements.

However, the flexibility comes at a cost: traditional URL‑based HTTP caching no longer works because each query can be unique, requiring custom cache implementations. Moreover, unrestricted query composition can produce deep, expensive data fetches that become performance bombs at ten‑million QPS, necessitating strict query‑complexity limits and governance.

Thus, for ultra‑high‑throughput core paths, predictable, cache‑friendly specialized APIs are often safer than GraphQL, which shifts complexity from interface definition to query governance.

Design Differences Between Million and Ten‑Million QPS

At the million‑QPS level, the extra bandwidth and extra downstream calls caused by a generic API are usually absorbed by system headroom; development efficiency dominates the design decision. At ten‑million QPS, those same overheads are amplified tenfold, turning previously tolerable waste into a system‑breaking bottleneck. The design focus shifts from convenience to resource efficiency.

The underlying mindset changes from "what can I provide" to "what does the caller truly need".

Step‑by‑Step Migration Path

Audit the current generic endpoint: enumerate callers, request frequencies, and which fields each actually uses.

Target the most painful scenario (e.g., product detail front‑page) and build a dedicated specialized API or BFF for it.

Deploy the new specialized interface alongside the old one, allowing callers to switch gradually.

Validate performance gains per migration step and continue migrating remaining callers until the generic endpoint can be retired.

This incremental approach minimizes risk and ensures that the system remains stable throughout the transition.

Conclusion

Moving from generic to specialized APIs is an almost inevitable evolution for systems that scale to ten‑million QPS. While generic endpoints accelerate early development, they become a heavy liability under extreme load. Specialized APIs, implemented via BFF layers or, where appropriate, GraphQL, restore resource efficiency by aligning the interface with actual caller needs. The key is to balance flexibility with predictability, applying the right pattern to the right scenario.