<p>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.</p>

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

<p>I am thinking in terms of usability, readability, efficiency etc.</p>

[{'answer_id': 62434, 'author': 'Staale', 'author_id': 3355, 'author_profile': 'https://Stackoverflow.com/users/3355', 'pm_score': 0, 'selected': False, 'text': '<p>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 <a href="https://rads.stackoverflow.com/amzn/click/com/0201633612" rel="nofollow noreferrer" rel="nofollow noreferrer">gang of four patterns book</a>. For Java specifically, and also just OO programming in general, I would recommend <a href="https://rads.stackoverflow.com/amzn/click/com/0321356683" rel="nofollow noreferrer" rel="nofollow noreferrer">Effective Java 2nd Edition</a>. The first is general and a lot 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.</p>\n'}, {'answer_id': 62728, 'author': 'Slavo', 'author_id': 1801, 'author_profile': 'https://Stackoverflow.com/users/1801', 'pm_score': 0, 'selected': False, 'text': '<p>Take a look at <a href="https://rads.stackoverflow.com/amzn/click/com/0321246756" rel="nofollow noreferrer" rel="nofollow noreferrer">Framework Design Guidelines</a>. I know it is .NET specific, but you can probably learn a lot of general information from it too.</p>\n'}, {'answer_id': 62813, 'author': 'yrp', 'author_id': 7228, 'author_profile': 'https://Stackoverflow.com/users/7228', 'pm_score': 3, 'selected': False, 'text': '<p>My two favourite resources on the subject: <a href="http://mollyrocket.com/873" rel="nofollow noreferrer">http://mollyrocket.com/873</a> and <del><a href="http://video.google.com/videoplay?docid=-3733345136856180693" rel="nofollow noreferrer">http://video.google.com/videoplay?docid=-3733345136856180693</a></del></p>\n'}, {'answer_id': 63426, 'author': 'Alex Miller', 'author_id': 7671, 'author_profile': 'https://Stackoverflow.com/users/7671', 'pm_score': 1, 'selected': False, 'text': '<p>The video from Josh Bloch mentioned by yrp is a classic - I second that recommendation.  </p>\n\n<p>Some general guidelines:</p>\n\n<ol>\n<li>DO define your API primarily in terms of interfaces, factories, and builders.</li>\n<li>DO clearly specify exactly which packages and classes are part of the API.</li>\n<li>DO provide a jar specifically used for compiling against the API.</li>\n<li>DO NOT rely heavily on inheritance or the template method pattern - over time this becomes fragile and broken.</li>\n<li>DO NOT use the singleton pattern or at least use it with extreme caution.</li>\n<li>DO create package and class level javadoc explaining usage and concepts.</li>\n</ol>\n'}, {'answer_id': 71496, 'author': 'Laserallan', 'author_id': 11758, 'author_profile': 'https://Stackoverflow.com/users/11758', 'pm_score': 2, 'selected': False, 'text': '<p>From using third party libraries on Windows I\'ve learned the following two things:</p>\n\n<p>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.</p>\n\n<p>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.</p>\n\n<p>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.</p>\n\n<p>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.</p>\n\n<p>The book "Imperfect C++" has some discussion on library compatibility that I found very helpful.</p>\n'}]
['https://Stackoverflow.com/questions/62398', 'https://Stackoverflow.com', 'https://Stackoverflow.com/users/6775/']