How do you define a good or bad API?

Question

Reference Information:

I take a class at my university called "Software Constraints". In the first lectures, we learned how to create good APIs.

A good example of the fact that we got a very bad API function is the public static void Select(IList checkRead, IList checkWrite, IList checkError, int microseconds); socket public static void Select(IList checkRead, IList checkWrite, IList checkError, int microseconds); in c #. The function receives 3 lists of sockets and destroys them, forcing the user to clone all sockets before submitting them to Select() . It also has a timeout (in microseconds), which is an int that sets the maximum timeout by the socket server. The limits of this are +/- 35 minutes (because it is int).

---

Questions:

• How do you define an API as 'Bad'?
• How do you define an API as good?

---

Questions to consider:

• Names of functions that are difficult to remember.
• Function parameters that are difficult to understand.
• Poor documentation.
• Everything is so interconnected that if you need to change 1 line of code, you really need to change hundreds of lines in other places.
• Functions that destroy their arguments.
• Poor scalability due to hidden complexity.
• It is required that the user / dev create wrappers around the API so that it can be used.

Answer 1

In the design of the API, I always thought this keyword was very useful:
How to create a good API and why it matters - Joshua Bloch

Here is an excerpt, I would recommend reading all this / watching a video.

II. General principles

• API should do one thing and do it well
• API should be as small as possible, but not less
• The implementation should not affect the API
  
• Minimize the availability of everything
  
• Matter API names are a small language
  
• Documentation Issues
  
• Document religiously
• Consider the performance implications of API design decisions
• The effects of performance development APIs are real and permanent.
• The API must coexist peacefully with the platform.

III. Class design

• Collapse Mutability
  
• Subclass only where it makes sense
• Design and document for inheritance or other prohibitions.

IV. Method Design

• Do not force the client to do anything the module can do.
• Do not break the principle of least surprise
  
• Fail Fast - Report bugs as soon as possible after
• Provide programmatic access to all data in string form
• Overload with care
  
• Use appropriate parameters and return types
  
• Use a consistent parameter order in all methods
  
• Avoid long lists of options
• Avoid returning values ​​that require exceptional handling

Answer 2

You do not have to read the documentation to use it correctly.

A sign of amazing API.

Answer 3

Many coding standards and longer documents and even books (Framework Design Guidelines) were written on this subject, but much of this helps only at a fairly low level.

There is also a matter of taste. APIs can obey every rule in any rule summary and still suck due to slavish adherence to different ideologies in fashion. A recent culprit is the orientation of the template, which uses Singleton Patterns (a little more than initialized global variables) and Factory Templates (a way to parameterize the construction, but often implemented when they are not needed). Recently, it is more likely that Inversion of Control (IoC) and its associated explosion in the number of tiny interface types, which adds unnecessary conceptual complexity to the design.

The best tutors to taste are imitation (reading a lot of code and API, figuring out what works and doesn't work), experience (making mistakes and learning from him) and thinking (not just doing what is fashionable for his site, think before) than to act).

Answer 4

• Useful - it eliminates a need that is not yet satisfied (or improved on existing ones).
• Easy to explain - a basic understanding of what he is doing should be easy to understand.
• It follows some object model of any problem domain or real world. It uses constructs that make sense.
• Proper use of synchronous and asynchronous calls. (don't block things that take time)
• Good default behavior - if possible, extensibility and customization, but provides default values ​​for everything that is necessary for simple cases.
• Use cases and working examples of applications. This is probably the most important.
• Excellent documentation
• Eat your dog food (if applicable)
• Keep it small or segment it so that it is not one huge contaminated space. Keep feature sets excellent and isolated with few dependencies.

Eat more, but it's a good start.

Answer 5

A good API allows the client to do almost everything they need, but does not require a lot of meaningless busy work from them. Examples of "meaningless busy work" will be the initialization of data structure fields, calling several subprograms in a sequence that never changes without real user code between them, etc.

The surest sign of a bad API is that your customers all want to wrap it with their own helper code. At least your API should have provided this helper code. Most likely, it should have been designed in such a way as to provide a higher level of abstraction, which customers ride on their own each time.

Answer 6

A good API has a semantic model close to what it describes.

For example, the API for creating and processing Excel spreadsheets will have classes such as Workbook , Sheet and Cell , with methods such as Cell.SetValue(text) and Workbook.listSheets() .

Answer 7

I always liked this queued article titled "API Design Considerations"

http://queue.acm.org/detail.cfm?id=1255422

And these columns also relate to API design issues:

http://queue.acm.org/detail.cfm?id=1229903

Answer 8

A bad API is one that is not used by the target audience.

A good API is one that is used by the target audience for the purpose for which it was designed.

An excellent API is one that is used both by its target audience and for its intended purpose, and an unintended audience for reasons unforeseen by its designers.

If Amazon publishes its API as SOAP and REST, and the REST version wins, this does not mean that the underlying SOAP API was bad.

I would suggest that the same would be true for you. You can read everything you want about design and try everything you can, but an acid test will be used. Take some time to get feedback on what works and what doesn't, and be prepared to refactor as needed to make it better.

Answer 9

A good API is one that simplifies simple things (minimal template and learning curve to do the most common things) and complex things (maximum flexibility, as few assumptions as possible). The middle API is one that does one of them well (either insanely simple, but only if you are trying to do really basic things or insanely powerful, but with a really steep learning curve, etc.). A horrible API is one that does nothing good.

Answer 10

There are already several other good answers to this, so I thought I would just throw some links that I did not see.

Articles

• Jasmine Blanchett of Trolltech's "Little API Design Guide"
• "Definition of QT-Style C ++ API" also Trolltech

Books:

• Effective Java by Joshua Bloch
• Kernigan and Soldering "programming practice"

Answer 11

I think a good API should let you configure IO and memory management, if applicable.

A typical example: you have your own compressed archive format for data on disk, and a third-party library with poor api wants to access data on disk and expects a path to a file where it can load its data.

This link has some good points: http://gamearchitect.net/2008/09/19/good-middleware/

Answer 12

If the API generates an error message, verify that the message and diagnostics help the developer decide what the problem is.

My expectation is that the calling API will correctly input the input. The developer is the consumer of any error messages generated by the API (and not the end user), and messages directed to the developer help the developer debug his calling program.

Answer 13

An API is bad if it is poorly documented .

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

Now these are two, very simple and very difficult points that lead to the field of software architecture. You need a good architect who structures the system and helps the structure follow its own guidelines.

Commenting on the code, writing a well-explained guide for the API is a must.

An API can be good if it has good documentation explaining how to use it. But if the code is clean, good and complies with the standard within itself, it does not matter if it has decent documentation.

I wrote a little about the coding structure here

Answer 14

I think that readability is of paramount importance, thanks to which I mean the quality that makes the greatest number of programmers understand what the code does in the shortest possible time intervals. But to judge what part of the software is readable and which does not have that indescribable human quality: fuzziness. The points you are talking about partially succeed in crystallizing it. However, in general, it should remain in each case, and it would be very difficult to develop universal rules.