When is an API overengineered? [closed]

Answer 1

Two (related) questions to ask yourself come to mind immediately:

• Are there things that can be done in more than one way?
• Are there methods/properties on the API that can be expressed in terms of the rest of the API?

More difficult to answer, and not a sign of overengineering in itself, but definitely a sign the API isn't as simple as it could be yet:

• Are there other methods/properties you can introduce that would make it possible to remove more than you introduced (based on the other two questions)

Answer 2

"What are some warning signs from a developer's perspective that your API might be overengineered?"

No use cases.

If you can't run through simple "to do this" scenarios, you're not designing a useful API with specific use cases in mind.

Your documentation should be those use cases.

Features that don't directly address the use cases are probably over-engineering.

Answer 3

Start to worry when you have a large API with a lot of functions which, on closer inspection, turn out to be compositions of simpler operations. An API with a high ratio of composition mechanisms to primitives is usually a good design.

(API design is very similar to language design, and here I am essentially espousing the Scheme philosophy—instead of piling more routines into the API, simplify it and include composition mechanisms that render the additional routines unnecessary.)

Answer 4

when the stack trace for a common api call requires you to scroll the screen to see the entire thing.

Answer 5

When using the API is: (1) more obtuse, more complex, less efficient, and less predictable than just using the underlying technology, AND (2) does not offer a significant advantage for safety, scalability, or cross-platform freedom.