How are poor APIs designed and what processes birth them

#discuss

There are well-designed APIs, and there are APIs that are badly designed. It's a no brainer that a well-designed API makes life easier for everyone.

While there are lots of articles on APIs best practices, I would like to know how poor APIs are designed and what processes birth them.

Thanks for your contributions.

Top comments (7)

Austin S. Hemmelgarn • Dec 25 '19

Most of the time when an interface (API, ABI, or even other stuff like UIs) is poorly designed, it comes down to one or more of the following issues:

The design was deferred to a late stage in development and is thus limited by the implementation details of whatever it's an interface for.
The design was never properly formalized, and thus just kind of happened.
There was a major time constraint on the design and implementation of the interface.
The designer is new to designing that type of interface.
The designer did not think of the interface from the perspective of a user.

Note that all of these can be avoided pretty easily, and also that none of them guarantees a bad API, they just make it more likely.

Phil Ashby • Dec 25 '19

I would add that even a good designer needs real consumer feedback (preferably contract tests!) early, to iron out all the use cases they would never think of themselves, and to work hard on retaining flexibility in the implementation behind the API so it can evolve along with those consumers needs. Few things suck worse than having to maintain a poor API that neither customers nor the product team actually want, but are stuck with through sunk costs (they often assume..)

Samuel James • Dec 25 '19

I totally agree with you. :)

Austin S. Hemmelgarn • Dec 25 '19

The first one is easy, design your interface right after you decide what a component is supposed to do, and then code to the interface. This has additional advantages, because you can use the interface specification to test the implementation as you go along.

The second one is usually a symptom of the first or third, and can be avoided by just making sure to properly specify your interface.

The third, when it happens, is often unavoidable. The ways to try and avoid it happening are pretty much the same as for any software project, do as much as you can to avoid having a hard deadline that is out of sync with a realistic estimate of how long it will take to finish things.

The fourth is best mitigated instead of being avoided, and is best mitigated by having multiple people review the interface design the same way you review code changes.

The fifth also benefits from review from multiple parties, but the most reliable way to avoid it is to have people who will be using the interface involved in it's design.

In all cases, the most common reason they're not avoided is either simple laziness, or the developers not thinking they're going to be an issue.

Samuel James • Dec 25 '19

Awesome tips. Thanks for this.

Shivan Moodley • Dec 25 '19

I think a major factor in the quality of APIs is the point at which they are actually designed. I find that the later in your dev process you try to design your API for usage, the lower the overall quality would be. It moves the design away from being focused on the contract of data in/data out and more onto the implementation detail of the application. Which in turn can lead to really hard to use/understand APIs.