Introduce an interface, then swap what's behind it.
You're replacing one implementation with another — a new database, a new service, a new API protocol — and want to do it incrementally without a big-bang cutover. The key insight is that by placing an abstraction boundary between consumers and the implementation, you can build the replacement behind the same contract and switch over without touching any consumer code.
You'll know this technique applies when you find yourself thinking "we need to swap out X for Y." That thought is your signal: the abstraction IS the first PR. The interface defines the contract that both the old and new implementations must satisfy, which means you can validate the new implementation in production long before any user actually sees it.
How this looks in your git history:
The engineering team needs to migrate from REST API calls to GraphQL for loading product data. The current codebase has direct fetch() calls to the REST API scattered across multiple components — each component that loads products has its own inline fetch logic mixed with rendering code.
We'll introduce a ProductDataSource interface, build a GraphQLProductDataSource behind it, add a factory that selects the implementation via config, flip the config switch, and then remove all the REST code. At no point does any consumer change after PR 1.
Define a ProductDataSource interface with the three operations consumers actually use — getProduct, listProducts, and searchProducts. Create RestProductDataSource implementing the interface, with the existing fetch logic moved verbatim inside it. All call sites are updated to receive a ProductDataSource via dependency injection rather than calling fetch directly.
This is a pure structural change — identical behavior. Every existing test passes without modification. What we've gained is the abstraction boundary: consumers now depend on the interface, not the fetch calls, which means we can swap what's behind it without touching a single component.
| line number | line content |
|---|
Create GraphQLProductDataSource implementing the same ProductDataSource interface using GraphQL queries. The class uses a shared gqlFetch helper, three typed query constants, and maps the GraphQL response shapes to the Product and ProductSearchResult types the interface requires.
Nothing calls this class yet — it ships to production as dark code. No users see any change. We ship it now to give ourselves the option to test it against staging, run it in a shadow mode, or route a small percentage of internal traffic to it before the switch.
| line number | line content |
|---|
Create src/lib/products/index.ts with a createProductDataSource() factory that reads the PRODUCT_DATA_SOURCE environment variable and returns the matching implementation. The singleton productDataSource is exported from this module — all consumers import from here, not directly from either implementation class.
The default is still 'rest', so behavior is unchanged for all users. The wiring is now in place for a one-line switch in the next PR. Consumers don't change at all — they already depend on the ProductDataSource interface, not the concrete class.
| line number | line content |
|---|
Change the default in createProductDataSource() from 'rest' to 'graphql'. This is the entire PR.
This is the payoff of Branch by Abstraction: the migration that required four PRs to prepare is executed with a single character change. No consumer code changes, no risk of regressions — just a config default flip. The old REST implementation is still present in case a quick rollback is needed, but the GraphQL path now serves all traffic.
| line number | line content |
|---|
Delete RestProductDataSource from data-source.ts, remove the factory function and the DataSourceKind type from index.ts, and replace the singleton with a direct new GraphQLProductDataSource(). The diff here shows index.ts shrinking from 20 lines to 4 — the full cleanup also removes the RestProductDataSource class from data-source.ts.
Clean final state: no switching logic, no dead code, no environment variable that future engineers will wonder about. The abstraction layer served its purpose and the interface remains, now implemented exclusively by GraphQL.
| line number | line content |
|---|
Making the abstraction too leaky. The interface should be expressed in terms of the domain — products, not HTTP. If your ProductDataSource interface has methods like buildRestUrl() or formatGraphQLQuery(), you've leaked an implementation detail into the contract. Both implementations would then need to satisfy an interface shaped for one of them. Define the interface from the consumer's perspective: what operations do components need? Those become the interface methods.
Skipping the validation phase between "build new" and "remove old." The factory in PR 3 exists precisely to give you a period where both implementations are in production code, even if only one is serving traffic. Use this window: run smoke tests against the GraphQL implementation in staging, shadow-traffic it against production, or let it serve a small percentage of requests before committing to PR 5. Going straight from PR 2 to removing the REST code skips the confidence-building step that makes the technique safe.
Extracting an interface that's too broad. Don't model the interface on everything the REST API can do — model it on what your consumers actually use. If no component ever calls deleteProduct(), the interface should not have it. Broad interfaces create unnecessary implementation burden for the new data source and become a maintenance liability as the codebase evolves.