The Most Expensive Boolean in Your API
A parameter named includeInactive looks harmless. Then someone adds includePending. Later there is skipValidation. A year later the same endpoint has a dozen behaviors whose combinations were never tested.
Boolean flags are seductive because they avoid creating a new method or a new request type. They also hide intention. A call like Fetch(true, false, true) asks the reader to memorize positional semantics or inspect the declaration every time.
Some flags represent legitimate filters. includeArchived=true may be a perfectly reasonable query parameter. The problem starts when flags change the meaning of an operation: preview versus commit, dry run versus execute, validation versus no validation. Those are different actions with different risks.
Where the distinction matters, use an explicit operation or a named policy. PreviewImport and CommitImport are easier to protect, test, observe, and audit than a single Import function whose third boolean decides whether writes occur.
This is also a compatibility issue. Once external callers depend on flag combinations, you must preserve behaviors you barely intended to expose. API versioning cannot repair an ambiguous contract by itself.
Before adding a boolean to a public API, list every new combination it creates. If half of them make no sense, the shape of the API is wrong.
Top comments (0)