Discussion on: How are poor APIs designed and what processes birth them

[Austin S. Hemmelgarn]

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:

1. 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.
2. The design was never properly formalized, and thus just kind of happened.
3. There was a major time constraint on the design and implementation of the interface.
4. The designer is new to designing that type of interface.
5. 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]

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]

I totally agree with you. :)