I just wrote this article on API design for Elsevier’s SciTech blog. It talks about the importance of hiding implementation details and covers information hiding techniques for C++, Objective-C, and Python, such as the pimpl idiom and class extensions. The article includes a discount code for 40% off my book, in case you’ve been waiting for the price to come down before buying it!  Check it out at:

• http://scitechconnect.elsevier.com/1-rule-api-design/

Ferenc Mihaly maintains a blog call the Amiable API where he posts various articles on API design. As part of this blog, he provides a checklist of dos and don’t in API design. The list is focused on the Java programming language, however, most of what Ferenc presents it applicable to other languages too. I really like the bullet list format and the use of verbs to produce a concise yet extensive set of general rules to consider when developing an interface.

• http://theamiableapi.com/2012/01/16/java-api-design-checklist/

The folk at apigee have distilled everything they’ve learned about Web API design over the last few years into a new free eBook called “Web API Design: Crafting Interfaces that Developers Love.” This collates many of the details from their various blog posts into a single reference, covering topics such as REST, handling errors, versioning, authentication, complementary SDKs, and many others. If you’re writing a Web API for your platform this is a great read.

• http://blog.apigee.com/detail/announcement_new_ebook_on_web_api_design

Brian Mulloy at Apigee wrote a short article on versioning for Web APIs where he contrasts three different methods of including versioning information in a URL. These include using a timestamp or version number in the URL path, or accepting a version number as an optional parameter. Brian suggests using a mandatory version number as far left in the URL as possible, and using a whole number instead of dot notation for your versions.

• http://blog.apigee.com/detail/restful_api_design_tips_for_versioning/

If you want to read something a little longer than a blog article on how to build REST Web APIs then there are a few books out there that may be of interest to you:

• REST API Design Rulebook
• Restful Web Services
• RESTful Web Services Cookbook
• REST in Practice

In this Twilio Engineering blog article, Frank Stratton makes the point that computers don’t care about API design. APIs should be designed for human beings first and computers second. Using example Web APIs developed at Twilio, he talks about the need for having many eyes and minds see the design first, simplifying the surface area of your API, and how it is easy to add new calls but hard to remove existing ones.

• http://www.twilio.com/engineering/2011/10/31/apis-are-for-human-beings/

Noah at 37 Signals wrote about API design for Web APIs. The key point he makes is about the need for strong documentation and having that documentation in an easy-to-search format. He then talks about authentication, advocating that an API offers multiple authentication schemes. Finally, he talks about building REST-like interfaces.

• http://37signals.com/svn/posts/3018-api-design-for-humans

Ferenc Mihaly has created a blog called The Amiable API dedicated to designing developer-friendly APIs. This web site grew out of a set of internal guidelines that Ferenc produced for his company and ultimately decided to publish in a blog format. Some of his recent posts include: Choosing memorable names, Striving for consistency, Keeping it simple, Considering the perspective of the caller, and Why developer-friendliness is central to API design.

• http://theamiableapi.com/

Finish software house Reaktor has published some slides on how to design good APIs. The authors, Jari Mäkelä and Ville Peurala, make the point that bad APIs can infect client code and lead to bad client code too. They state that some elements of good design include being intuitive, easy to learn from simple examples, self explanatory, and effort minimizing. A good API should make correct usage easy and wrong usage difficult or impossible. They provide a number of code examples of bad and good API design decisions – these examples are in Java but are pretty vanilla and easily applicable to other languages. The slides are provided as a PDF download at:

• http://reaktordevday.fi/slides/ApiDesign-ReaktorDevDay.pdf

Daniel Rabinovich has put together a slide set on REST API design choices for Web-based interfaces. Daniel recommends using standard HTTP verbs, like PUT and OPTIONS. He also talks about being able to specify the returned fields (a performance optimization) and notes that selection, multiget, and search are REST violations with hidden costs (harder to cache or shard). Daniel covers a lot more topics, so see his slides for more details:

• http://www.slideshare.net/DanielRabinovich/api-design-choices

David Zeuthen has written a long and detailed article on many of the design issues that are faced when trying to write a plain C API. He deals with aspects such as library initialization, multithreading, error handling, versioning, and testing. It’s well worth a read if you are interested in writing a library in plain C (rather than C++). David’s collection of best practices is split into 5 parts, as follows:

• Part 1: Base libraries, Library init/shutdown, memory management, threads/processes
• Part 2: Event handling and the main loop, sync/async I/O
• Part 3: Modularity, namespaces, error handling, OO design
• Part 4: Helpers, daemons, and testing
• Part 5: API Design, documentation, and versioning

George Reese wrote an article to summarize his experiences using various SOAP and REST cloud computing APIs. His tips include:

Good: Support JSON and XML, prefer REST over SOAP, provide meaningful error messages and solid API documentation.
Bad: Avoid OAuth and HTTP authentication for system-to-system interactions, add throttling thoughtfully and carefully, avoid chatty APIs that require many calls.
Ugly: Don’t return HTML in your response body and understand how to return HTTP error codes.

For the full article, see:

• http://broadcast.oreilly.com/2011/06/the-good-the-bad-the-ugly-of-rest-apis.html

Trek Glowacki wrote an article about how to get your Web-based API right. He advocates the use of HTTP, using verbs to name end points, keeping your URIs consistent, using your HTTP status codes correctly, supporting multiple data formats, using OAuth or HTTP Authentication as appropriate to protect your users, and finally documenting your API well. For more details, check out the entire article:

• http://wonderfullyflawed.com/2009/07/02/get-your-api-right.html

Michael DeHann wrote a blog article relating some of the things he’s learned about good API design. This includes advice such as programming with a view to the outsider, naming classes appropriately, figuring out how to make your code better through experiencing bad code, provide documentation that obviates the need for users to ask you how your code works, avoid redundant code, avoid extraneous conversions where possible, keep logic with the class that owns it, avoid adding complexity to your code through many options, and finally test your code but focus on functional end-to-end tests.

Many of these design tips are not new, but Michael provides a fresh perspective on them that I think is worth reading. Check out his post at:

• http://michaeldehaan.net/2011/04/29/class-api-design/