Inspired by a conversation with Kin Lane (aka @apievangelist) and Mike Amundsen (@mamud) at last years APIDays conference in Paris, I decided to dig deeper into the SDK vs API debate.

Over the last couple of months I had noticed a pattern of using API SDK’s rather than the underlying Web API’s. Lets quickly define what I mean by SDK. There used to be a time not too long ago when SDK meant documentation, code samples, build scripts and libraries all bundled together. Today you find all of the former on a website and usually only the library remains. When I use the term SDK I mean a programmatic API (JS, Ruby, PHP, Python) on top of the Web API (usually REST/Json)

As it happens my wife gave me a small wearable activity monitor for Christmas as a present (I could not possibly think of any reason why I would need that - and the new weight scale in the bathroom must have been pure coincidence). Since the gadget was uploading my stats to a cloud service, and this cloud service had an API, and my wife gave it to me as a present, I figured I had a perfect excuse to do some coding. My goal was to write a client-side app using Javascript pulling my stats from the cloud service via the API (and keep notes on my experiences).

After registering at the developer portal I hit my first stumbling block - no client-side javascript SDK. The closest I could find was a PHP SDK - which ofcourse meant that I had to install PHP (I had not used PHP before), and the framework(s) used by the SDK and enable a webserver and debug the SDK’s OAuth implementation. That was not quite what I had in mind. Even though I got it running after one and a half day I ended up being quite frustrated. All that work for a simple webpage displaying the stats for a hardcoded day. So I decided to take a different approach and use the SDK provided by Temboo. Again no client-side Javascript SDK. While I could have used a Node.js SDK instead, I decided to stick with my PHO install and opted for the PHP SDK. From there the integration was quick and I was up and running within an hour. What I did not like about the SDK was the footprint (it included all possible integrations) and how its abstraction and data presentation leaked into my application code. If I were to build a commercial product using it I would have to consider the potential stickiness of the SDK. Personally - this did not feel right either. So I went back to the drawing board and looked at my options.

What had I learned so far - my frame of reference going into the experiemnt was a client-side app using java script. Yet the only SDKs I had found were written for server side integration. Since it was the only choice offered to me, I had to invest a significant amount of time finding all the necessary information to get the server-side components and dependencies installed and configured. But even after going through all of this the experiences with either form of SDK left something to be desired.

I had started this excercise thinking that using a SDK was much easier than coding againsthe Web API - maybe it was time to revisist that assumption.

Looking back at the API documentation I could not find anything inherently difficult. Looking at the vendor provided PHP SDK it dawned to me that the entire complexity of the client was due to OAuth and the use of XML as payload. This finally gave me the opening I had been looking for. If I could avoid the complexities of OAuth on the client and use JSON as payload format, I should be able to implement my client-side app with a few lines of javascript against the Web API. As a regular guest at Webshell’s API Days conference I was familiar with WebShell’s OAuth Broker service oauth.io . It took me a few minutes to get setup and configure the service and download their oauth.js client library. I cut and pasted the sample code into a javascript file, looked up in the API docs on how to switch to Json format and did the API call - and was done in less than 5 lines of code.

While this experiement is just a single data point I think is nicely illustrates some of the key lessons in the SDK vs API debate. I will attempt to provide a summary both from an API consumer and API provider perspective in my next blog entry. I will also be talking about the SDK vs API issue in more detail during the upcoming Nordic API tour in Stockholm and Copenhagen and at the API Days Berlin conference.