Service Asymmetry

Imagine we're the programmers responsible for building a software service. Along comes a user and asks for a new API:

.

The product manager records the feature request in our backlog, prioritizes it relative to the other feature requests, and we build it when it becomes the top priority.

Our work is straightforward; the user is (eventually) satisfied. Peace and order reign in the land.

Now, what happens when we want to remove a feature to simplify our code? Or, more generally, make breaking changes to an existing feature?

Now, rather than users asking us (the engineering team) to change, we're asking them to change. This is much harder.

Why is it harder? Well, there's one engineering team, but there's probably not just one user. Any feature that we build has a large audience, and is inevitably going to accumulate many different users.

Trying to get many users to change how they do things is much harder than getting one engineering team to change something. It's a simple matter of scale.

There's also the question of who is paying whom for their work. Programmers don't pay users to adapt to breaking changes. Your users might tolerate having to do a little bit of work in exchange for the ability to keep using the software, but it won’t make them happier.

Finally, the fact that breaking changes are usually motivated by technical needs rather than business needs makes it hard to get buy-in from all stakeholders. Your users have their own backlog of work they need to get done; they're not eager to add "adapting to a breaking API change" to their to-do list. If users drag their feet, who will you escalate to? Will you be able to make the case for your API change to your manager’s manager? What’s the actual business reason to drop support for the old API?

The consequence of all these factors is that it's easy to add features to software, but difficult to remove them. Every feature you add is, in effect, a promise to your users that you'll maintain that feature. It's easy to make promises, harder to keep them, and painful to break them.

• How might we prevent users from coupling their code to internal implementation details of our system that we want to be able to change later?

• How might we give users what they need without over-promising (i.e. exposing extra APIs and data that they don't need)?

• When we need to make breaking changes, how might we keep the old API available while users are switching over to the new one?

• Incrementally adding a bunch of special-purpose APIs creates its own kind of mess. Are there design principles that can help us get a general-purpose API right the first time around?

• Even if we can't get it right the first time, are there principles that could help us get it wrong in a way that can be made righter without any breaking changes?