in pursuit of making SDKs suck less

17 Mar 2015

This is a follow-up from a previous post on SDKs being crap. My points in that post still stand for the most part, because, well, most SDKs suck. But being in the business of designing and building APIs, I can’t escape them, and soon I’ll have to be building and maintaining them at notion. In other words, for me, the question is no longer why do I have to keep using SDKs that suck,1 but how do I make them not suck?

My main gripes with SDKs are that they tend to be incomplete (e.g. I end up having to just make an HTTP request because the SDK doesn’t provide a method to wrap that request), poorly documented, or just one more layer adding complexity between me and an API.2 Also, from the point of view of the provider (a start-up provider at that), each SDK is one more library to maintain - and who’s got time for that? I would love to spend half my time writing articles and documentation to help educate developers on how to interact directly and easily with an API using HTTP, but ultimately, if I want to make things easier for devs (who also don’t have much time), sure, education is part of that,3 but so is giving them the tools to do amazing things faster and more reliably.4

So how can I make an SDK that helps more than hurts?5 How do I make an SDK that not only makes my API more accessible, but more manageable? Can an SDK enrich the experience of using an API?

The number one thing first and foremost must be maintainability.6 This is a really loaded word here. It means that I as the provider should not have to exert a ton of effort to fix bugs, keep it up to date with API patches or different versions, etc. It also means that client devs shouldn’t have to put in a load of work just to use it (or figure out how to use it) or debug problems. Practically, and perhaps somewhat obviously, this means making sure your SDKs are open-sourced7, well-documented, and really not more complex than a simple wrapper around your API.

But what I’m really excited about is the potential of SDKs to help consumers with exploiting hypermedia to explore and keep up with changes in the API. Until hypermedia evolves and starts to see more adoption by client developers, SDKs offer a great opportunity to leverage hypermedia and get hypermedia into the mainstream, while increasing maintainability. Maintainability, because the SDK can expose the API and its resources through the links given in responses or through the API spec (following apis.json or json.schema) so the provider as to do less hard-coding, but also because of awesome developments in the ability to generate hypermedia clients directly from your API documentation spec – meaning all you have to do is keep up with your documentation.8

I’ll be working on implementing some hypermedia SDKs in the near future and writing about my failures and successes, but in the meantime, check out these cool projects and resources:

1 Not that I've used SDKs since I wrote that post, mind you.
2 See further discussion here.
3 Not to mention witty and utterly convincing blog posts by yours truly.
4 What? You mean I'm building software for other people?
5 Read: helps way more. Actually, read: helps and doesn't hurt at all.
6 Can you tell I'm trying to avoid explicitly writing a numbered list? Is it working? If you think so, tweet @switzerly to give me mad props; otherwise, you can keep your thoughts to yourself.
7 So I can offload all the bug-fixing and README-ing to other people.
8 And, of course, documentation should be at the top of your priorities anyway.

Slán go fóill,
Shelby at 06:50