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,¹ 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.² 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,³ but so is giving them the tools to do amazing things faster and more reliably.⁴

So how can I make an SDK that helps more than hurts?⁵ 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.⁶ 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-sourced⁷, 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.⁸

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:

• Hyperclient
• HyperResource and the paper
• The Hypermedia Project
• Mike Amundsen’s “Implementing Hypermedia Clients: It’s Not Rocket Science”
• Rob Zazueta’s API and Hypermedia version of “stop planning and start building” - because flexibility, adaptability, and maintainability are the real aims here