Discomfort as a Tool for Change

2 min read Original article ↗

Thanks for the question, taeold. I agree that all else being equal, if you make something more expensive it'll happen less.

Usually API changes are actually additions. It's hard to change the black box behavior of a service in a loosely-coupled system because you have to convince all clients to migrate to expect the new reponse.

Off the top of my head, API definitions or black-box behavior can change for several reasons:

1) The API leaks implementation details and the implementation needs to change for some reason.
2) A new feature is added.
3) The domain changes. (typically rare)
4) There is an error in the implementation that leaks bad API responses.

API owners are motivated by management performance reviews. For 2-4, they will be given poor marks if they do not respond to defects and changing business demands, so they will implement the changes and update the Fake despite the additional cost.

Almost all bad APIs I've seen are examples of 1. This is a symptom of a bad design and probably made the Fake hard to write in the first place. In a system that hides no implementation details, the Fake is as complicated as the original system. I would hope that teams in this situation would come to the awareness of their fundamental problem and fix it since that would lower long-term costs for everyone.

A few years ago I worked with a team whose primary query API sent clients the entire storage record, which was a kind of state machine snapshot, consisting of dozens of poorly-defined, nested, high-cardinality fields. Clients generally only needed one or two pieces of data, but they had little guidance as what was public and unchanging and often picked an internal, implementation-specific field to use. The service owners didn't know what clients needed because they were internally focused. Imagine how hard that API would be to support with a Fake and how motivated that team would be to learn what the domain actually was and implement an API using that knowledge if a realistic Fake was mandatory.

Dave

p.s. In case you're curious, the team eventually did move to a better API. They came to realize how much their API constrained their implementation since any internal change was a potential hard-to-debug defect only caught in integration tests.