The One-Size-Fits-All (OSFA) REST API

Yesterday ended with a new problem: Netflix now had an API layer sitting between its clients and hundreds of microservices, and it had to decide how that layer should be shaped. The first answer was the one almost every engineer reaches for: build one clean, generic, well-designed API and have every client use it. Netflix later named this the One-Size-Fits-All (OSFA) API.

The reasoning felt airtight. You have one catalog, one set of users, one library of titles. Why would you build the API more than once? Design it well once, document it, and let the TV app, the phone app, the console, and the browser all call the same endpoints. This is the industry-standard instinct, and Netflix followed it.

The OSFA API was a RESTful API. REST (Representational State Transfer) is a style for designing web APIs around resources — the "nouns" of your system, like a title, a user, or a queue — each addressable by a URL, and manipulated with the standard HTTP verbs.

• GET reads a resource, POST creates one, PUT/PATCH updates, DELETE removes.
• Each resource has a stable URL, for example /users/42 or /titles/8080.
• Responses are generic representations of those resources — the same shape no matter who asks.

GET /users/42/queue HTTP/1.1
Host: api.netflix.com
Accept: application/json

{
  "userId": 42,
  "queue": [
    { "titleId": 8080, "addedAt": "2013-04-01" },
    { "titleId": 6122, "addedAt": "2013-03-28" }
  ]
}

This is "resource-oriented" design: the API exposes the underlying data model as a set of addressable resources, and every client navigates that same model. It is clean, it is standard, and — crucially — it looked like exactly the right call at the time.

The OSFA REST API had genuine, real virtues. It is worth being fair to it, because these are the same virtues that make REST the default choice for most APIs even today.

• Clean and standard. REST is widely understood. A new engineer or a new client team can read the resource model and know how to use it. There is a single source of truth for "how do I get a user's queue."
• One implementation to maintain. The API team builds each resource once. No duplicated logic per device.
• Cacheable. Because a GET on a resource URL returns the same generic representation to everyone, standard HTTP caching (CDNs, proxies) can store and reuse those responses — a big performance and cost win.
• Decoupled in principle. Clients depend on the resource contract, not on the internal microservices behind it. The API team can rearrange the backend without breaking clients, as long as the resource shapes hold.

For a system with a handful of similar clients, this design is not just defensible — it is correct. Netflix's problem was that it did not have a handful of similar clients.

Here is the fact that broke the one-size-fits-all assumption. Netflix does not run on one kind of screen. It runs on over a thousand different device types: smart TVs from dozens of manufacturers, streaming sticks, game consoles, iOS and Android phones and tablets, Blu-ray players, set-top boxes, and desktop browsers.

These devices are not just cosmetically different — they differ in ways that matter deeply to an API:

A single generic resource model cannot be ideal for all of these at once. It can only be a compromise — and the compromise showed up as two concrete problems.

A generic, resource-oriented API forces clients to assemble a screen from many small, granular resource calls. Each of those calls is a round-trip: one full request from the device to the server and back. When a screen needs many round-trips, we call the API chatty.

Consider a TV home screen built on OSFA REST. To render it, the device might have to:

Each round-trip pays the full latency cost of crossing the network. On a constrained device over a slow or high-latency mobile connection, dozens of sequential round-trips add up to a home screen that is slow to appear. And because the generic API returns generic resources, each response also carries fields the device does not need — wasted bytes on a device with a tight memory budget. The generic design is, by construction, both too chatty and too heavy for the constrained end of that thousand-device spectrum.

The second problem was organizational, and it turned out to matter just as much. In the OSFA world, the API team owns the one API. Every UI/device team that wants the data shaped differently — a new field, a combined response, a device-specific tweak — has to file a request with the API team and wait.

The device teams know exactly what their screen needs; the API team owns the code that can deliver it. That split means the people with the knowledge are not the people with the keys. Every device-specific need becomes a ticket in the API team's queue, the API team becomes a shared bottleneck between the UI teams and the services, and the whole organization moves at the speed of that one team. As Netflix added more device types and more UI teams, this bottleneck got worse, not better.

Step back and the diagnosis is clear. The OSFA REST API optimized for the server's convenience — one clean model, one implementation, easy caching — at the expense of the clients' wildly different needs and the UI teams' autonomy. It was generic, and its genericness was exactly the problem: a generic API cannot be efficient for a thousand specific devices, and a single API team cannot be responsive to a dozen specific UI teams.

Netflix's response was not to refine the generic API. It was to invert the whole idea — to stop building one API for all clients and instead let each client shape its own. That inversion is Day 3.

• Netflix's first API-layer design was One-Size-Fits-All (OSFA): a single clean, generic REST API that every device type used.
• REST is a resource-oriented style — nouns (users, titles) addressed by URLs and manipulated with HTTP verbs, returning the same generic representation to every caller.
• OSFA seemed right for good reasons: clean and standard, one implementation, cacheable via HTTP, and decoupled from the backend in principle.
• It broke against reality: Netflix runs on 1000+ device types with wildly different screens, networks, and memory budgets, so one generic model can only be a compromise.
• Problem one — chattiness: a generic API makes constrained devices do many sequential round-trips (and over-fetch fields), producing slow, heavy screens.
• Problem two — bottleneck: the single API team sat between UI teams and services, so every device-specific need queued behind them and the org moved at one team's pace.
• The core tension: OSFA optimized server convenience over client diversity and team autonomy — which set up Netflix's decision to invert the design entirely.

• [ ] I can explain what "One-Size-Fits-All (OSFA)" API means in Netflix's history.
• [ ] I can define REST and resource-oriented design and give an example resource URL.
• [ ] I can state the genuine advantages that made OSFA look like the right choice.
• [ ] I can explain why 1000+ device types make a single generic API a compromise.
• [ ] I can define round-trip and chattiness and describe the round-trip problem on a constrained device.
• [ ] I can explain why the single API team became an organizational bottleneck.
• [ ] I can articulate the core tension (server convenience vs client diversity + team autonomy) that motivated the next redesign.