When is an API overengineered?

Question

I despise working with overengineered APIs that don't make simple things simple. Nonetheless, I'm working on designing an API for an open-source library and I'm starting to feel that I'm falling into the overengineering trap. I really can't tell for sure because, of course, I wrote the darn thing, so how it works is more obvious to me than anyone else. What are some warning signs from a developer's perspective that your API might be overengineered?

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

These seem relevant:

http://stackoverflow.com/questions/469161/how-do-you-define-a-good-or-bad-api http://stackoverflow.com/questions/750112/overengineering-how-to-avoid-it

Answer 4

When reviewing the documentation and examples, the percentage of verbiage discussing the API in relation to itself cmpared to the percentage of verbiage discussing its application to credible use cases.

Answer 5

As S.Lott said, use-cases. They will determine what exactly your API should be directed towards doing. If you design your API to complete a very clear, specific goal - functionally coherent - you are most likely going to end up with an API or component in your API that is both easy to use and understand.

Designing an API should be like designing a user interface. Most all concepts of UI can be embraced by an API, for example, the KISS principle or even Kaizen.

I'd link to those UI concepts, but I'm a new user so they won't let me post more than 1 hyperlink. Good example there: StackOverflow, let us know before we post ;).

Answer 6

You should check out the Google Tech Talk How To Design A Good API and Why it Matters by Joshua Bloch ... he covers a lot of this stuff.

Answer 7

When it's so clever that nobody else can understand it.

Answer 8

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

Answer 9

One trick I found very useful and it has helped me in the past is write doc before, during, and after you code.

When designing an API to be used by other people I usually document the design before writing code. If I was over engineering the design, the design spec usually full of conflicts and nonsense.

During coding, I usually stub out the class definition and function body and start writing doxygen comments for them. In the comments I'll have use case, sample code, and assumptions of the interfaces. During this phase, before too much real code is written, the class interface usually gone through redesign multiple times. I know I was over engineering when the sample code is hard to write and I have a hard time explaining the interface. A lot of the bad design ideas are exposed and eliminated when you try to explain to people how to use your API.

After coding, I replace the sample code in the comments with real compiled and tested code copied from my unit tests and further document the behavior of the interface. Another sign of over engineering is when my unit tests cannot keep up with the interface change because there are too many moving parts and too many ways to do the same thing and unit tests growth at an exponential proportion.

Answer 10

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.

Example, IMHO: LINQ. Developers are now not learning basic SQL because they think everything should be abstracted in C# calls. It's like formatting a web page only with JavaScript calls so you can avoid learning the syntax of CSS. Lame.

Answer 11

In my experience you can tell when the whole project is held up for months, waiting on the API to be finished.