Middleware API Best Practices, What are they?

Question

We are developing a middleware SDK, both in C++ and Java to be used as a library/DLL by, for example, game developers, animation software developers, Avatar developers to enhance their products.

What I would like to know is this: Are there standard "Best Practices" for the development of these types of API?

I am thinking in terms of useability, readability, efficiency etc.

Answer 1

There are lots of ways to design apis, depending on what you are solving. I think a full answer to this question would be worthy off a whole book, such as the gang of four patterns book. For Java specifically, and also just OO programming in general, I would recommend Effecitve Java 2nd Edition. The first is general and alot of popular programming patterns, when they apply and their benefits. Effective Java is Java centered, but parts of it is general enough to apply to any programming language.

Answer 2

Take a look at Framework Design Guidelines. I know it is .NET specific, but you can probably learn a lot of general information from it too.

Answer 3

My two favourite resources on the subject: http://mollyrocket.com/873 and http://video.google.com/videoplay?docid=-3733345136856180693

Answer 4

The video from Josh Bloch mentioned by yrp is a classic - I second that recommendation.

Some general guidelines:

1. DO define your API primarily in terms of interfaces, factories, and builders.
2. DO clearly specify exactly which packages and classes are part of the API.
3. DO provide a jar specifically used for compiling against the API.
4. DO NOT rely heavily on inheritance or the template method pattern - over time this becomes fragile and broken.
5. DO NOT use the singleton pattern or at least use it with extreme caution.
6. DO create package and class level javadoc explaining usage and concepts.

Answer 5

From using third party libraries on Windows I've learned the following two things:

Try to distribute your library as a DLL rather than a static library. This gives way better compatibility between different c compilers and linkers. Another problem with static libraries in visual c++ is that the choice of runtime library can make libraries incompatible with code using a different runtime library and you may end up needing to distribute one version of the library for each runtime library.

Avoid c++ if possible. The c++ name mangling differs alot between different compilers and it's unlikely that a library built for visual c++ will be possible to link from another build environment in windows. When it comes to C, things are much better, in particular if you use dll's.

If you really want to get the good parts of c++ (such as resource management through constructors and destructors), build a convenience layer in c++ that you distribute as source code that hides away your c functions. Since the user has the source and compiles it locally, it won't have any name mangiling or abi issues with the local environment.

Without knowing too much about calling c/c++ code from Java, I expect it to be way easier to work with c code than c++ code because of the name mangling issues.

The book "Imperfect C++" has some discussion on library compatibility that I found very helpful.