Tim Murphy's .NET Software Architecture Blog

May 2012 Entries

Document Your APIs

I have been working on a Windows Phone application for the user group that I help to run and have been experiencing head ache after head ache.  The problem isn’t the Windows Phone development itself.  The issues are with the external web service APIs that I am trying to use for sites like SlideShare and Box.net. 

The main issue is that while there is a lot of documentation and examples for the output of the APIs, the input format is sketchy at best.  The web service for SlideShare, for example, requires that a set of values be hashed using SHA1, but there is not example of what the format of those values should be prior to being hashed.  That mean there is a lot of head bashing trial and error and error and error. 

Anyone who publishes a public API should realize that users of that API are not going to have knowledge of the internal workings of their product (and shouldn’t).  You can’t even expect them to have the same tools either.  Given that this is a web service being used the calling applications could be on any number of platforms using an equally large number of languages.  The only way to ensure proper usage of your tools is to explicitly document the parameters of your interfaces and mountains of examples.  The easier you make it for developers to code against the greater the adoption will be for your API.  Let’s all remember this going forward.