How do you define a good or bad API? [closed]

Answer 1

A good API is one that makes simple things simple (minimum boilerplate and learning curve to do the most common things) and complicated things possible (maximum flexibility, as few assumptions as possible). A mediocre API is one that does one of these well (either insanely simple but only if you're trying to do really basic stuff, or insanely powerful, but with a really steep learning curve, etc). A horrible API is one that does neither of these well.

Answer 2

If the API produces an error message, ensure that the message and diagnostics help a developer work out what the problem is.

My expectation is that the caller of an API passes in input that is correct. A developer is the consumer of any error messages produced by the API (not the end user), and messages aimed at the developer help the developer debug their calling program.

Answer 3

I think what is paramount is readability, by which I mean the quality that makes the greatest number of programmers to make sense of what the code is doing in the shortest possible amount of time. But judging which piece of software is readable and which is not has that indescribable human quality: fuzziness. The points you mention do partly succeed in crystallizing it. However, in its entirety it has to remain a case-by-case affair and it would be really hard to come up with universal rules.

Answer 4

A good API allows the client to do pretty much everything they need to do, but doesn't require them to do a lot of mindless busy-work. Examples of "mindless busy work" would be initializing data structure fields, calling several routines in a sequence that never varies with no real custom code in between, etc.

The surest sign of a bad API is if your clients all want to wrap it with their own helper code. At the absolute least, your API should have provided that helper code. Most likely, it should have been designed to provide the higher level of abstraction the clients are rolling themselves on their own every time.

Answer 5

There are several other good answers on this already, so I thought I'd just throw in some links I didn't see mentioned.

Articles

1. "A Little Manual Of API Design" by Jasmin Blanchette of Trolltech
2. "Defining QT-Style C++ APIs" also Trolltech

Books:

1. "Effective Java" by Joshua Bloch
2. "The Practice Of Programming" by Kernighan and Pike

Answer 6

An API is bad when it is badly documented.

An API is good when it is well documented and follows a coding standard.

Now these are two, very simple and also very hard points to follow, this brings one into the area of software architecture. You need a good architect that structures the system and helps the framework follow its own guidlines.

Commenting code, writing an well explained manual for the API is Mandatory.

An API can be good if it has a good documentation which explains how to use it. But if the code is clean, good and follows a standard inside itself, it doesnt matter if it doenst have a decent documentation.

I've written a little about coding structure here