Monday, April 23, 2012

Designing APIs

Today I got a reference to a post published by Charlie Kindel about an extreme point of view (maybe rather an extreme post title) of why API design and publishing can become a nightmare.

Kindel is a former Microsoft guy behind a lot of Windows tools including Windows Media Center where I had the opportunity to work with him during a couple of MCE projects we did while I was working for Schematic (now Possible Worldwide).

I did some research around since at this point of my career I have been involved in the design, development, publishing and maintenance of several APIs for different projects, platforms and companies. Designing good APIs is hard, and designing robust and maintainable APIs is even harder. I agree on that with Charlie. Once you publish an API you can't change have to live with it forever...until you have to kill it !

Here's a summary of the article and my personal opinion:
  • APIs need to be well designed and proved from the beginning.
  • Public APIs will be used in ways you can't foresee.
  • Once an API has clients and users, you will need to support it forever.
  • APIs are better when they are easy to use, consume and understand.
  • APIs are better when they are simpler and condensed.
  • APIs should be public only when there's a strong reason and a real world scenario for them. 
Charlie was kind enough to share a really good presentation about API design best practices by Joshua Bloch, Principal Software Engineer of Google.

I have published a few posts about APIs implementation taking advantage of Microsoft's WCF Framework to expose APIs that can be exposed as SOAP or HTTP endpoints, which I have used in several projects with great results and I believe the article and the document are quite relevant and helpful for everybody out there dealing with public APIs. 

Although I know I'm not adding a lot of value to Kindel's already published post, I wanted to log this on my blog and make sure to share the document's link with all of you. I really hope it helps.



  1. Hi,

    Really nice advices. Now I'm dealing with some legacy code and we have changed the current structure to from static modules to use dynamic modules (sort-of like plug-in base). The problem with this it's that the legacy app wasn't design to support plug ins, so I had to manage to organize and protect part of the core functionality (other than the issue of creating a plug in structure). I'll double check the presentation ;-)

    Perhaps I'd categorize API depending on the target. API for third parties in order to extend my application or for internal usage. And also If it's a Web API or an API for desktop apps. I think there are subtle differences when implementing API depending on those targets.


    1. Thanks for sharing Herberth. I believe the case you exposed is fairly common when working with exposed APIs. Is good to remember that you can have internal system APIs or public APIs, but no matter what you always face the maintainability issues and considerations.

  2. More on APIs, here is this good blog post about components that any company designing and exposing APIs should take into consideration