12

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?

Joel Coehoorn
  • 399,467
  • 113
  • 570
  • 794
dsimcha
  • 67,514
  • 53
  • 213
  • 334
  • 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 – Jason Weber Jun 04 '09 at 02:55

11 Answers11

19

"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.

S.Lott
  • 384,516
  • 81
  • 508
  • 779
11

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.

John MacIntyre
  • 12,910
  • 13
  • 67
  • 106
  • 3
    +1, was going to link to it, as well - the slides are also available: http://lcsd05.cs.tamu.edu/slides/keynote.pdf – none Jun 04 '09 at 03:30
  • 3
    Here, you can view the video and the slides together, embedded in the same browser view: http://www.infoq.com/presentations/effective-api-design – none Jun 04 '09 at 03:36
  • To be frank, much of the APIs Bloch had built is over-engineered imho. Nevertheless there are good takeaway points in that video – Pacerier Nov 15 '11 at 04:08
5

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.

Shing Yip
  • 1,596
  • 1
  • 12
  • 11
4

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

Mark
  • 2,932
  • 18
  • 15
2

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.

dkretz
  • 37,399
  • 13
  • 80
  • 138
2

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 ;).

Tres
  • 5,604
  • 3
  • 19
  • 17
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)
jerryjvl
  • 19,723
  • 7
  • 40
  • 55
1

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

Damien
  • 1,463
  • 1
  • 18
  • 30
1

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.)

Norman Ramsey
  • 198,648
  • 61
  • 360
  • 533
0

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.

Gabe
  • 84,912
  • 12
  • 139
  • 238
richardtallent
  • 34,724
  • 14
  • 83
  • 123
0

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

TWA
  • 12,756
  • 13
  • 56
  • 92