March 27th, 2014

SDK vs API – Round 2

SDK vs APIInspired by a conversation with Kin Lane and Mike Amundsen at last year’s APIdays conference in Paris, I decided to dig deeper into the SDK-vs-API debate.

As I wrote in my last post, I had noticed a pattern of using API SDKs rather than the underlying Web APIs. Let’s quickly define what I mean by SDK. There used to be a time, not so long ago, when “SDK” meant documentation, code samples, build scripts and libraries all bundled together. Today, you find all the former on the Web and usually only the library remains. When I use the term SDK, I mean a programmatic API (e.g. 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 as a Christmas 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 to 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, of course, meant that I had to install PHP (I had not used PHP before) and the framework(s) used by the SDK. I also had to enable a Web server and debug the SDK’s OAuth implementation. That was not quite what I had in mind. Even though I got it running after one day and a half, I ended up being quite frustrated. All that work for a simple Web page 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 PHP 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 experiment was a client-side app using JavaScript. 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 experience with either form of SDK left something to be desired.

I had started this exercise thinking that using an SDK was much easier than coding against the Web API – maybe it was time to reassess that assumption.

Looking back at the API documentation, I could not find anything inherently difficult. Looking at the vendor-provided PHP SDK, it dawned on me that the complexity of the client was entirely 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 the 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 APIdays conference, I was familiar with the company’s OAuth Broker service. It took me a few minutes to get set up, configure the service and download their oauth.js client library. I cut and pasted the sample code into a JavaScript file, consulted the API docs to learn about switching to JSON format and did the API call. I was done in less than five lines of code!

While this experiment is just a single data point, I think it nicely illustrates some of the key lessons in the SDK-vs-API debate. I will attempt to provide a summary from both the API consumer and the API provider perspectives in my next post. I will also be talking about the SDK-vs-API issue in more detail during the upcoming Nordic APIs tour in Stockholm and Copenhagen and at the APIdays conference in Berlin.


  1. [...] SDK vs API – Round 2 [...]

    Pingback by SDK vs API – Round 2 | Holger Reinhardt — March 27, 2014 @ 1:47 pm

  2. [...] to the production stage, Holger Reinhardt from Layer 7 cautioned developers to avoid the SDK trap. Sharing his personal research and distilling the key findings for the Nordic APIs audience, he noted that the two main problems [...]

    Pingback by Seven Key Messages From Nordic APIs that Got Developers Talking — April 8, 2014 @ 11:30 am

  3. [...] seems to involve using an SDK rather than the API itself. I followed up with a post talking about my decidedly mixed experiences of trying to use SDKs. My own experiences inspired the headline of this post: SDKs work until they [...]

    Pingback by Layer7 Blog: SDKs Work Until They Don’t | Holger Reinhardt — April 24, 2014 @ 2:19 pm

RSS feed for comments on this post. TrackBack URL

Leave a comment