Feature Flags Turn Every User Into a Different API

Feature flags are a genuinely good idea — ship code dark, roll it out gradually, kill it instantly if something's wrong, without a deploy — and they come with a testing cost that's easy to underestimate: every flag you add doubles (at least) the number of distinct behaviors your API can actually exhibit, because "the API with the flag on" and "the API with the flag off" are, from a consumer's point of view, two different APIs that happen to live at the same URL.
Why this is easy to lose track of
A single boolean flag means your endpoint has two real behaviors to account for. Two independent flags mean four combinations. A team with a dozen active flags, even if most combinations are rare in practice, has a combinatorial testing surface that grows far faster than the number of flags does — and unlike a versioned API, where "v1" and "v2" are visible and deliberate, flag combinations are often invisible in a request: two identical-looking requests from two different users can get completely different responses, and nothing in the request itself tells you why.
This is exactly the kind of thing that produces a very specific, maddening bug report: "it works for me but not for this other user," where the actual difference is that the two users are on opposite sides of a flag rollout, and nobody debugging the ticket initially thinks to check.
What actually needs to be tested
A reasonably disciplined approach doesn't try to test every combination of every flag (usually neither feasible nor worthwhile) but does deliberately cover:
- Each flag's on state and off state independently, for any endpoint the flag actually affects — not just the state currently live for most users, which is the one that gets accidentally over-tested by default because it's what everyone sees when they poke at the app normally.
- The transition itself, for flags a user can flip mid-session (an in-app upgrade, a settings toggle) rather than only ones fixed at login — does the UI update correctly, or does it need a full reload to reflect the new state, and if so, is that actually acceptable?
- Combinations that are known to interact, even if you can't test every combination exhaustively — if two flags are known to touch the same code path, their interaction is worth a deliberate check, not an assumption that testing each independently covers the pair.
- The flag being unexpectedly unavailable — a flagging service being briefly unreachable shouldn't crash the app; it should fall back to a sensible default, and that fallback path is itself untested unless someone deliberately tests it.
Making a specific flag combination reproducible
The awkward part of testing flag-gated API behavior against a real backend is that flipping a real flag for a real test account, for just long enough to test one specific combination, is either slow (waiting for a flag management UI and propagation delay) or risky (accidentally leaving a flag flipped for real users while you're testing). Mocking the flagged endpoint directly sidesteps this: define the "flag on" response and the "flag off" response as two routes distinguished by a header or query param your test harness controls, via conditional matching, and you can switch between every combination you care about instantly, without touching a real flagging system or a real user's account state at all.
The API didn't get more complicated because feature flags are a bad idea — they're not. It got more complicated because every flag is a fork in what "the API" even means for a given request, and forks you don't deliberately test are exactly the ones that eventually show up as "works for me, not for them."
Xerat02
Building MockBase.
More from the blog

API Keys, JWTs, and OAuth2 Are Answering Different Questions
All three end up in an Authorization header, which is exactly why they get treated as interchangeable — but "prove you're allowed," "prove who you are," and "prove someone else said it's fine" are three different problems.

Build the Frontend First: A Practical Guide to API-First Development
Waiting for the backend to exist before you can build the UI against it is a scheduling problem, not a technical one. Here's how teams actually break that dependency.