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 

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.

Posted On Wednesday, May 9, 2012 1:20 PM | Comments (0)

Tim Murphy

Tim is a Solutions Architect for PSC Group, LLC. He has been an IT consultant since 1999 specializing in Microsoft technologies. Along with running the Chicago Information Technology Architects Group and speaking on Microsoft and architecture topics he was also contributing author on "The Definitive Guide to the Microsoft Enterprise Library".

I review for the O'Reilly Blogger Review Program

Technorati Profile
Tag Cloud