While it’s extremely important to have quality API developer experience, it does not stop at great API design or at the documentation level. One of the most important elements of great developer experience is the SDK.

For app developers, an SDK is often the point of entry to elements within the API. Every forked API, every secondary function, and every business-to-business functionality could be driven chiefly by the SDK and its functions. Having bad developer experience for SDKs is akin to poisoning the root system of a fruit tree — even if it were to grow, the fruit it bears would be poisoned, or at east very bitter.

Today, we’re going to discuss how to make the SDK ecosystem as strong as possible – in effect, making our roots healthy, robust, and powerful. We’ll offer some best practices for building a good SDK, and thereby forming a strong and robust API network.

What Is an SDK?

Before we can give good advice on building an SDK, we should actually define what an SDK is. Simply put, an SDK is a Software Developer Kit that includes all the information and pieces needed to create a specific application. In this case, an SDK for an API includes all of the information and pieces needed to create an application that utilizes that API in new and powerful ways — in other words, it acts as a guidance system for integration.

Ideally, an SDK should include libraries, tools, relevant documentation, samples of code and implementations, process explanations and examples, guides for developer usage, limitation definitions, and any other additional offerings that would facilitate building functions that leverage the API.

Best Practices

With this in mind, what best practices can we identify for SDK creation?

Keep it Simple

Any SDK, and really, any API for that matter, is only worthwhile if the average user can actually utilize it. Overly complex codebases, archaic implementations, and labyrinthine methodologies can stymie usage, killing an SDK and its associated projects with amazing efficiency. Ensuring simplicity throughout all stages is a great basis to build upon.

While there’s a wide range of approaches to this problem, there are actionable steps developers can proactively take to simplify the result. First and foremost, prioritize classes and methods that are most commonly used. This will allow the SDK to display the functions utilized by the user without obfuscating options with a deluge of methods or functions that can’t actually be utilized.

As part of this, the codebase itself can help ensure simplicity in the SDK. Utilize as few parameters as possible, using only that which is needed to get the specific function done. As a corollary to this, do not over-simplify and combine multiple functions into a single parameter set unless they are related – while this might seem the ultimate in simplification, once it goes too far, it actually begins to add more complexity than it’s worth.

Simplicity is about form and function – keep this in mind while simplifying the SDK codebase.

Make it Usable

As mentioned previously, an SDK is valued by its function. As such, ensuring usability is fundamental. This can be done in a variety of ways. First, providing a use guide, perhaps in the form of a Getting Started primer, can help introduce the user to not only the SDK itself, but the intricacies and the peculiarities of your code approach.

Ideally, a user should be able to start using the SDK within 5–10 minutes of introduction, assuming they’re familiar with the language and function of the codebase it represents. Structure your Getting Started guide around this goal.

It’s also very important to ensure that the widest possible breadth of users can actually utilize your service. Accordingly, offering SDKs that integrate into the API codebase in a wide variety of languages can help expand the range of options available to more users.

It’s important to note that as you expand your language offerings, however, you must ensure that you are correctly supporting these integration offerings. Utilizing correct file types, encoding systems, and general code methods is important, as utilizing a common language with a proprietary syntax is no better than using a non-common language in the first place.

Map Endpoints Correctly

SDKs are like roadmaps — they provide a guide for navigation. Therefore, when building SDKs, ensure your mapping is correct.

Endpoints must actually map the same way in your SDK as they do in your API. Make these connections clear as far as what ties into what, why this is so, and what the intended functions and expected responses are.

Make sure that the SDKs are continually updated. Deprecated code, class names, functions, etc. do not reside in the SDK if they no longer reside in the API – leaving these in would be akin to having any crossover roads and intersections on a map that don’t actually exist, nullifying much of the navigational value to the average user.

As an adjunct to this, ensure that functions correspond to their function and are appropriately named. While this is good form for the API itself, in the SDK, it’s arguably even more important. usernameSubmit is more appropriate than unmeSbt, regardless of whether the second name might be a personal shorthand utilized by the developer for speed or out of pure habit. Using clear and consistent naming will not only make SDK utilization easier, it will also result in a clearer communication of expected function, acting as a sort of ad hoc documentation.

Finally, ensure that any new functionality is immediately added and defined within the SDK, and that it is notated in any documentation. Hidden classes should only exist for security reasons, not because someone forgot to add it. This, and truthfully all of the preceding suggestions, are easily implemented when utilizing any of the many options offering automatic SDK generation and documentation generation from an API codebase.

Document the SDK Too

It’s common to think of an SDK as a form of documentation for the API in addition to a development tool. However, focusing only on the SDK as a form of documentation results in a situation in which the technically minded, who are more likely to understand functions in the first place, are the only ones with any valuable documentation upon which to lean.

Accordingly, providing ample documentation not only of the API, but of the SDK as well, is incredibly important. Aside from trial and error, this will be the primary system that developers, both experienced and otherwise, utilize as a point of integration. Poor documentation of both the SDK and its functions would break this workflow. Ensure that you’re writing clearly for both technical and regular users to ensure universal understanding, unobfuscated by jargon.

A great tool in this space is the use of ReadMe files and changelogs. These will help explain directly the current version of the SDK, as well as the mindset of the development team when changes are justified. This will also help ensure a line of communication between developers and users, which is paramount to a healthy user interaction and user experience in general.

Publish Appropriately

It’s very important to also ensure that your API can be accessed appropriately, and that this access is publically navigable. If your userbase is primarily concerned with open source forking, security, and development, having your SDK published utilizing GitHub and its associated repositories as an open-source project can ensure excellent results.

Alternately, if your API is closed down or otherwise requires privacy of codebase, then it makes more sense to utilize a proprietary SDK and documentation methodology, with the understanding that this comes with certain caveats and expectations should be measured.

Developers should also consider publishing in an offline-friendly way, allowing for documentation and SDK perusal without an internet connection. This can be done in a variety of ways, as complex as a purpose-built desktop application down to the most simple PDF file. Regardless of the method, this should be considered dependent on your userbase and their specific needs, and the stipulations of your platform policies.

Final Thoughts

In essence, an SDK is a direct conduit to the mind of the API creator. The various methods, systems, integrations, and offerings from the API creator are not only present (as they are in the API itself), they are well-explained and demonstrated — in this way, an SDK offers a set of tools for creation, yes, but also offers a channel of communication that is direct, customizable, and wholly managed by the API provider to explain and describe in their own specific way.

Both a tool for creation and communication, an SDK should be considered a dual-faceted system of extreme importance.

Building a poor SDK also ensures that any communication between the developer and the user will likewise be poor, filled with guesswork and extrapolations that may or may not be true. To this end, following the few practices outlined herein will ensure that your SDK, as well as the systems that utilize it, will be as good as it can possibly be.

Do you have additional ideas on best practices for building SDKs? Please comment below!