The API industry thrives on the health of its users and developers. Accordingly, developer experience is an extremely important part of the development process. According to Stack Overflow, of the 50 million developer respondents, 21 million were considered professional developers — 42% of all respondents. Failing to support this massive group of users appropriately is a recipe for failure.

So, the question then is, how do we go about providing awesome developer experience? One step to accomplish this is to utilize SDKs and Code Samples as a key part of API documentation. What specifically are these concepts, though? And how should they fit into the overall strategy for API practitioners?

Today, we’re going to discuss exactly that.

What is an SDK? What are Code Samples?

SDK stands for a Software Development Kit. We’ve previously defined them on the blog as follows:

“SDK stands for “Software Development Kit”, which is a great way to think about it — a kit. Think about putting together a model car or plane. When constructing this model, a whole kit of items is needed, including the kit pieces themselves, the tools needed to put them together, assembly instructions, and so forth. An SDK or devkit functions in much the same way, providing a set of tools, libraries, relevant documentation, code samples, processes, and or guides that allow developers to create software applications on a specific platform. If an API is a set of building blocks that allow for the creation of something, an SDK is a full-fledged workshop, facilitating creation far outside the scopes of what an API would allow.”

An SDK then should be seen as a primary method by which developer users act upon your code. Providing an accurate, powerful, and useful SDK is core to the user experience, as well as the overall health of the API.

Code Samples are a bit different in that they are quite literally just samples of existing and functioning code. Unlike an SDK, which provides the tools to develop a functioning system, Code Samples are examples of such a system in action — the code may be used in production, or it might be entirely removed from the production environment. Most importantly, it provides code that works as an example of how applications should model themselves, and gives the developer a way to frame their understanding both of the API itself and of their own application.

Now, let’s explore 5 strong reasons to adopt SDKs and code samples are first-class components in your developer-facing initiatives:

1: Establish Super-Focused Support and Documentation

“[SDKs and Code Samples] are the things where the real complexity comes. If you are deciding to include SDKs and code samples in your developer portal, you need to be dealing with a lot of things, [such as which developer community to support].”

Developing an SDK allows you to not only provide powerful support and documentation but to narrow this support down to a very specific subset of your user base. Providing support for every possible permutation, every possible language variant, and every possible development environment in every single possible combination is a fool’s errand, and short of using a documentation generation solution like ASync or Swagger UI, is not realistic.

By developing an SDK, you can focus on a specific segment of the potential user base and provide clear, ample instruction on how to utilize your API in that language. This is hugely benefit adding, as you can not only cover the lion’s share of your development userbase, you can also guide this userbase to use solutions you view as most appropriate or most convenient.

That’s not to say this is exclusionary, of course – quite the opposite! An API can have many language variation SDKs, as is the case with the Facebook Graph API – the first step to doing this, however, is to start documentation around your core user base. Implement this in such a way that you can then port this support and documentation to other systems.

That being said, focusing on a specific segment can prevent early creep and can structure your SDK around the most commonly used language, and thus, the largest userbase.

2: Provide Shortcuts to Developer Understanding

“If we talk about SDKs alone, or API wrappers, if you are providing HTTP calls and the serialization and deserialization, the basic SDK is done – but what if you go an extra mile to help developers?”

Learning to use an API is almost like learning a new language. As anyone who has done this can tell you, this is incredibly difficult, time-consuming, and at times, frustrating. The API space is much the same, and as with any learning process, providing tips and tricks can massively help developers in the process of learning and retaining this information in a meaningful way.

A developer can learn how to use your system, but you can make this learning, and their following utilization, much more productive by isolating their learning to what is needed and what is unique to your specific API.

This is akin to a tabula rosa situation; yes, a person can learn a new language, but if you could run someone through a crash course of 90% of the most commonly used words, would this not result in better retention, quicker understanding, and more purposeful exploration? SDKs and Code Samples help developers learn the tools they need to get started quickly.

3: Cultivate the First Building Blocks of an API

“Code samples are the quickest part to your first hello world.”

While there is value in theoretical understanding, for most developers, real-world use is the most effective and can deliver more contextual understanding.

Accordingly, bridging that gulf between the first steps of a developer’s learning and the actual coding is important. Providing code samples is like providing the concrete foundation to a construction project – it may not be the sum total that is needed to finish the project, but it certainly is a leg up versus starting at the dirt floor and building from scratch.

It’s all about establishing context. Working samples can be understood, reverse engineered, worked upon, and contextualized.

This is hugely important, and for many people, is how they learn. Asking a developer to work on a technical application without having access to proper code examples is like asking a mechanic to learn how to work on an engine without ever having touched one in the past.

4: Remove Experiential Redundancy from the Developer

“The golden principle of developer experience – remove the redundancy from the life of developers”

Developers often find themselves faced with redundancy. Whether this means figuring out how calls route, learning through trial by error, figuring out specific eccentricities and caveats for your specific API implementation, or even just learning internal syntax, all of this ultimately becomes redundant, and often, frustrating.

Redundancy is a huge time cost for the developer, but there is more to be concerned about. Developers who find themselves frustrated by the internally redundant systems of an average API discovery process might simply start using band-aid fixes, coding until it just barely works and calling it good. This, in turn, could cause further issues to propagate.

Redundancy can be decreased with an SDK, especially when this SDK ensures the commonly used language is understood and supported. Additionally, ensuring that the calls are structured in a sensible way and that everything is heavily documented can avoid burnout.

5: Promote Developer and Community Goodwill

“Speak [the developer’s language] – let them consume your APIs by providing SDKs and code samples in their favorite language, and get a lot of love in return.”

Perhaps more than anything, an SDK is akin to a love letter to your developer community. Providing substance and tools to make their life easier bridges the gap between corporation and humanity, and can do wonders to promote goodwill between the two.

This is one of the best things you can hope for in terms of developer experience. Enabling community to form around your tech can support your API, and positively impact API users.

This love is of course often returned wholesale – this is the same concept that fuels FOSS, where the community feels they own a part of the project or are key to its development, leading to bug hunts, development of better solutions, and overall community health. Essentially, supporting the community is supporting the API.