This past weekend, I was innocently attending RESTFest in Greenville, SC, along with some of the biggest API geeks and fanatics I’ve ever met.1 Things were going smoothly — people were arguing about The One HyperMedia Type To Rule Them All, some devs from Apigee did demos of their new ZettaJS with LEDs and arduinos, and “state machines” kept gaining momentum as the conference’s actual topic (um, move aside HTTP RFCs) — when someone innocuously mentioned in their talk a truth that I had yet to admit to myself: SDKs suck.
Now, I have to admit2 that I’ve used (and some of my current apps still use) SDKs pretty frequently. I wish I could say that I enjoyed using them, that they were the gin and tonic to my Monday afternoon, or, at the very least, that they made my life a pinch easier as a developer — but I can’t.3 Some of them, whether they’re “marketed” (ugh) as gems or SDKs or POSes, are ridiculously patchy and return unhelpful messages (’yes, I will give you a “1” to let you know your HTTP request was successful and a “0” if it fails’ - that makes perfect sense, right, Mogreet?), and with others it might take some deep spelunking into the cavernous depths of API consumption to find the weak spots — but they’re always there.
Take Dropbox for example: I love Dropbox, their API and documentation and their extremely responsive dev support team. But if you check out my app that uses its API the most extensively, you’ll see the odd HTTP request here and there that I used in place of the standard DropboxClient class from their SDK. I’ve had to make direct HTTP requests for a couple of reasons, mostly being that the relevant SDK method doesn’t support some options that you can pass alternatively as query string parameters in an HTTP request. This begs the question, why not include the capability to attach any relevant parameter to the SDK method as optional keys in a hash? Why not make your SDK be able to handle any request your API can handle?
But those questions, while reasonable,4 are ultimately beside the point. Even if you use an SDK and even if it has good documentation, at some point you’re going to have to go to the core API docs to check out the endpoints, payload possibilities, and responses. Furthermore, the documentation for the SDK versus the normal HTTP documentation is not always consistent. One thing I find hilarious is that the Dropbox API documentation gives 5 options (xs, s, m, l, xl) for creating a thumbnail from its
https://api-content.dropbox.com/1/thumbnails/auto/path endpoint, but the Ruby SDK gives different options (small, medium, large, s, m, l, xl). What's more, none of the dimensions match at all (e.g. the SDK's "l" has different dimensions than the regular API's "l"). I had to use the Ruby SDK for this one just so I could play around with more size options. Surely it would make more sense not even if APIs and SDKs were consistent, but if APIs just had good HTTP documentation with examples so that developers could deal directly with the requests and responses instead of having to fool around with wrapper classes. It would save time, confusion, and frustration.
When I started coming to this realization, I felt betrayed. I trusted these pernicious little code packages called SDKs and the API developers who wrote them. Surely, I thought, they must have my best interests at heart. Why would they make these things and encourage me to use them, trojan horses that they are? Maybe some companies think they haven’t “made it” until they’ve created an SDK for at least one platform. Maybe some people try to make the barrier for entry to their API as low as possible — with the attitude that many developers don’t want to go outside the comfort zone of their particular language or platform so won’t use an API unless they can interact with it through a pretty Ruby class.5 If that’s actually the case, it’s sad. We should expect more from developers — if expecting that they be able to competently make, receive, and interpret HTTP requests and responses is indeed "more." Maybe the reason there aren’t better APIs in general is because so many developers who make them would prefer SDKs themselves, or because they think “we don’t need to put too much effort into making this simple and well-documented because we’ll just wrap it in an SDK later”. In that case, we should expect more from API builders — especially in terms of documentation.
I do realize that an argument for SDKs could be that it helps the developer through API version changes, so that they don't have to change all their HTTP requests to meet the new API requirements, but in all likelihood enough about your API is probably changing between versions that the consumer-developer is going to have to do some maintenance anyway. I vote let the consumer take care of writing their own wrapper classes for your API to maintain if they so choose. That way, they're not fooled into trusting that you're keeping your SDK up to date (or even consistent from the beginning) with your HTTP API, and you don't have the added guilt keeping you awake at night when you choose not to maintain those extra libraries.