I’ve been working with SDKs quite a bit this year, simple ones that wrap a bunch of API endpoints. The best bits of these SDKs isn’t just the delightful developer experience of using the clunky endpoints with the elegant SDK wrapping them. I mean, it is, but I already wrote about consistent and Delightful SDKs for Nordic APIs; today I want to cover the some of the “extra” things that make a big difference in the APIs.

Provide Escape Routes

Don’t force your users to be all-or-nothing with your SDK. A great example is with APIs that use access tokens of any kind; I work with a few that use JWTs. As a nice helper function to the user, the SDK will generate the JWT and send it with your request, which is great. The extra value is added when the user can also generate a JWT for their own use; you expose the functionality that the library uses so that developers can use it themselves if they want to.

Save Repetition

If there’s a particular piece of functionality that every consumer of the API is going to have to do, however small or well-documented, then add it to your SDK. I spent quite a lot of my life answering questions about how to handle a particular signature check to improve security on our APIs. I updated documentation, improved it, added examples …. once we put the feature into the SDKs, I don’t think I’ve thought at all about this feature since!

Helpers

Don’t be afraid to go a little beyond the boundaries of just a wrapper for an API call in what you do. For example, some of our APIs accept quite complicated JSON structures in the body of the requests. Every programming language can produce JSON but some make it easier than others. In PHP or JavaScript, you can pretty much throw some sort of data structure at the JSON function and something will happen. But when I came to create a Golang SDK, I found that things are not quite so simple in strongly-typed languages. Creating defined data structures that could be quickly used and then marshalled to JSON made the library much quicker to get up and running with – for me, as well as for the users I hope will follow and make good use of it.

Delightful but Unobtrusive

Keeping the presence of the SDK as a helper for a particular tech stack, but not a requirement, is a great aim here. SDKs give us tech-stack-aware functionality, and smoother experiences with autocomplete and supplementary dependencies included. But developers may well need to get away from the beaten track in ways that you can’t anticipate so I’ll always advocate adding small pieces but keeping the responsibility with the developer on choosing to mix in only the pieces that make sense for her project. Hopefully the examples here give you some ideas for your next library, too!