Stop Fighting the Remodel: API Design for Models That Outgrew Their Boundaries

Every domain model has a breaking point. At Netflix, ours arrived all at once—Ads, Games, Live events, and entirely new kinds of content. Each pulled the core entities in different, sometimes contradictory directions. The API that had been coherent for years began to fracture, and we hit the decision every architect eventually faces: Do I overload the existing abstractions until they fit OR commit to the remodel? Scary, right?

For most of Netflix’s history, we bought or made one kind of thing: a finished, on-demand, long-form video. The supply chain had one shape and two ends—someone who gives us content, and someone who processes and delivers it. A “Partner” lived in a single bounded context, with a shared meaning across the business.

Sports, live events, games, podcasts, and other forms of content, each break that shape differently. A partner delivering a finished movie does not look like a partner broadcasting a live event or publishing a mobile game.

• Games inverted the identity axis. A studio isn’t one engagement—it’s N titles with N provisioning lifecycles.
• Ads inverted the direction of money. Every prior partner was someone Netflix pays; an advertiser or agency pays Netflix.
• Podcasts, publishers, and creative content inverted the granularity. These are delivered as a stream of many small things, not a slate of a few big ones.

These shifts broke our core domain invariants—the rules the domain promises are always true. For example, “A partner has exactly one legal identity” or “A partner’s tax ID is unique.” Those aren’t fields, and you can’t split them by moving a column. Two domains that share an invariant are coupled even when they share no data and no code, because neither can change the rule alone.

I originally wanted to maintain the status quo and bend the data to fit the existing model, which led to unsatisfiable conjunctions and falsified data workarounds. However, I realized that there was a superior strategy: I could lean into redefining domain boundaries, redrawing them without disrupting consumer dependencies or system constraints. Yes, I could keep 100+ (100!) downstream consumers operating with zero downtown and no breaking changes!

Bounded contexts decided where the lines went. Microservices are what live inside the lines. APIs are the contracts across the lines — and good API design is what lets you redraw the lines later without breaking everyone. 

Ultimately, a clear delineation between domain boundaries (bounded contexts), internal implementations (microservices), and integration contracts (APIs) helped sustain system flexibility, enabling us to redraw boundaries safely as a continuous natural evolution of our business, without disrupting consumer dependencies.

Key Takeaways:

1. Bend vs. remodel - How to tell when a flat model has truly outgrown itself.
2. Loose coupling via GraphQL federation vs. data synchronization. A heuristic for extending a model across domains with thin references and federation instead of syncing/copying data — and handling data invariants across shared data.
3. Bounded contexts in an already-shared model - Splitting a monolithic entity into a stable core, plus independently evolving domain aggregates — without a big-bang rewrite, and where to put the seams.
4. Migrating 100+ consumers with zero downtime - A backward-compatible facade so that legacy and new models can coexist and consumers can migrate on their own schedule—not by a required mandate.