Downstream cost of interfaces

Last week I mentioned the consequence of not fixing problems upstream.

When we design software to be dependent on other systems, those systems become upstream dependencies. No interface to any system is “perfect,” there’s no such thing. But there are many systems that have interfaces that require excessively nuanced interpretation by downstream systems. This can happen for any number of reasons:

  • Not having a purpose for building the interface, so the interface is over-engineered in an attempt to support any purpose. Intent is not at all explicit in the interface. Changing such a generic interface can be extremely painful without knowing the needs of downstream systems.
  • Poorly designed interfaces can leave consumers to build the necessary components to interpret the results of upstream interfaces. Even simple things like using standard formats are neglected. Special programming must be re-invented by every consumer, or consumers have to find a way to share their interpretation logic. Even to do simple things like interpret a date.
  • Unresponsive upstream teams, that simply can’t or won’t work to alleviate these struggles for consumers, only make matters worse.
  • “You just have to know” becomes the rule, not the exception. Don’t get me wrong, there’s always something you just have to know. But, fewer surprises are preferred.
  • As upstream teams become burdened with maintaining existing functionality, it’s not uncommon for inaccuracies and complexities of their system to leak out of their interface. Consumers can be left responsible for enforcing constraints of the upstream system.

In the spirit of plugging the leak for spreading further; as a consumer it’s a good idea, at a minimum, to start by fixing these problems upstream of your own project. This may be a layer in between the upstream system and your own. Don’t let the problems leak into your own system. Handle the problems in this layer and work over time to push those “fixes” upstream. Or, at least share and collaborate on them with other consumers.

If you’re the producer of a system, vigilantly work with consumers to find the unnecessary hurdles they face. Take the time to handle those once and for all, for everyone, in the upstream interface. The reduction in support calls alone will pay dividends.