Software development kits (SDKs) are a major element of a successful developer support program. SDKs offer a comprehensive toolkit of libraries, samples, documentation, processes, and more to help developers create new and exciting applications, substantially reducing the headache of development.

While the value of an SDK is obvious, what may not be so obvious is how software providers create a valuable SDK. You could build it manually or leverage various tools on the market for SDK generation. Choosing whether to build or buy is a significant obstacle to developing and adopting an SDK.

Below, we’ll examine these two options to help clear the road ahead. We’ll explore some cases where buying or building makes sense and offer some tools to get you well on your way to SDK paradise.

The Purposeful Development of an SDK

Before we consider options to build or buy, it helps to clarify the purpose behind its development. This purpose can give some form and intent to the development pathway and indicate which path may be optimal.

Developers need support, and the level of support provided can often be the difference between a product that just does what it says on the tin and a product that is unique, powerful, and truly functional. SDKs give developers the toolset required to interact with and iterate upon your API, allowing them to focus on developing a critical tool rather than getting into the weeds of uncovering particular functions and systems.

It’s clear, then, that an SDK is not just a technical toolkit — it is as much a method of collecting systems and functions as it is a method of expressing form and intent. This gives us a bit of a clue as to which path may be best. The level of clarity and control over the API’s message, form, and intent will, in some ways, dictate whether an automated surfacing of functions is preferred over a tailor-built and deeply contextual custom offering is more appropriate.

We should also note what makes a quality SDK, as both the build and buy options have pros and caveats. A good SDK must be consistent and robust — it should offer accurate options for the end developer in a format that is understandable and internally consistent with itself. SDKs are also often the first line of defense in solving issues, and as such, they must be in-depth and designed for discoverability.

With all this in mind, let’s consider our first option: building an SDK.

Building an SDK

Building an SDK can be a daunting task, but it is ultimately one that grants the most control. Due to the steps required to build a good SDK, there are multiple points at which the design, intent, and ethos of the API provider can be validated and instilled, creating both a technical tool as well as a communication pathway between the provider and the developer.

A variety of terms can describe these steps, but roughly, software providers will follow this same general practical outline:

• Design: Determine the form and function of your SDK, including the particular methodology to surface endpoints and functions.
• Validate: Utilizing an API specification or other like-system, validate the API to ensure that your understanding of the API reflects the situation on-the-ground. SDKs and documentation should adhere to the actual structure of the API in situ, and ensuring this is the case is a major step towards creating useful systems.
• Build: Now you can get to the process of actually building the SDK. This will be a very time consuming process, but it’s worth focusing on the details and specificity of how you build this out. Converting your API model and specification into usable endpoints and components will be vital. Ensure you have proper authentication and authorization methods, and implement clear error handling.
• Document: With the SDK developed, it’s time to document it. Documentation is a huge part of your SDK success pathway, and you should ensure that this documentation is accurate to the SDK as it exists. With each new element you add — API, CLI, SDK, documentation, and so on — information can drift out of context and out of sync. Ensure that you have created review and synchronization systems to prevent this.
• Share: Share your SDK with your users! Developer portals, development guides, Discord, or Slack can all be used as part of a cohesive developer support strategy that can help surface the SDK and its associated documentation. Make sure your SDK is discoverable — if it can’t be found, it won’t be used!

Building SDKs can be very time-consuming, but by following a few simple principles — keeping it simple, usable, correctly mapped, well-documented, and published appropriately — your SDK development journey can be highly rewarding.

Pros

• This process grants the developer complete control over the SDK, both in terms of content and intent. This can be major for the provider, establishing a significantly beneficial communication pathway.
• Building allows developers to spread this process over time. Automated systems tend to be all-or-nothing, but manual construction can be paused, given a different scope or schedule.

Cons

• Building an SDK manually is time-consuming and costly. This process will likely incur significantly more costs.
• Manually updating SDKs can be a long-term cost sink both in terms of time and resources, and it can be less clear upfront how much this cost might be.
• Building an SDK introduces a human element as a risk into the development pipeline, introducing inaccuracy at scale.

“Buying” Your SDK

When we discuss the idea of “buying” an SDK, we’re really talking about using third-party tools and off-the-shelf components to generate an SDK without any intentional development by an internal team. In essence, we’re taking something that already exists and creating an SDK from that system.

For example, we can look at how payment vendor Square generated their SDK using OpenAPI Specification. In this process, Square focused on the creation of an Open API Specification to design its API and document its endpoints. From here, Square then utilized Swagger Codegen, a solution that automatically creates an SDK via a system to templates. In this way, Square was able to generate SDKs using an off-the-shelf open-source tool without having to manually create it, gaining additional benefits in long-term management in the process.

There are various tools for generating SDKs, ranging from static open-source projects to fully-fledged SDK generation platforms and utilizing specific specification and definition paradigms. A sampling of these solutions include:

• APIMatic: A comprehensive developer experience platform that provides tools to automatically build and maintain SDKs.
• Appwrite’s SDK Generator: A backend-as-a-service platform that uses a PHP library to generate SDKs from Twig templates.
• Fern: An open-source SDK generation solution that utilizes a compiler to bundle functions, creating SDKs, documentation, and backend code from a single API definition.
• OpenAPI Generator: An open-source SDK generation solution that generates SDKs, documentation, and configuration data. This project is a fork from Swagger Codegen and supports various clients and languages.

Pros

• Buying your SDK may be more expensive than creating it by hand, but it is infinitely cheaper in terms of ongoing effort. Utilizing a pre-developed tool can get your SDK running without bogging your team down for a long time.
• Maintenance and long-term updates are typically automatic instead of manually developed, meaning you save time in the long run.
• This is also typically a solution that results in quicker market deployment with less overhead.

Cons

• Speed does not equate to accuracy, and code generation carries risks stemming from poor or incorrect definitions and an inaccurate codebase. This ultimately means your team may lose some efficiency and speed in the process of creating an SDK if you don’t pay proper attention in the early days.
• Buying your SDK can sometimes be more expensive, depending on your team setup. If your role is already focused on documentation, it may be a sunk cost compared to doing something external to the organization. That being said, the additional cost of long-term maintenance may make this a moot point.

To Build or Buy?

With so many options, finding a path through the noise is complex. Ultimately, your choice to build or buy will depend highly on your team structure, the maturity of your code, and if you embrace specification-driven API development.

Immature or small codebases that aren’t defined in a specification may benefit from building an SDK, as your total work will be substantially lower. That said, if your codebase is planned to become more complex, you will likely benefit from the additional process of documenting and specifying now.

Mature code that is accurately defined in a specification may benefit from “buying” your SDK, as you’ve already done the hard work of defining your API. This can result in significant cost savings but places a lot of dependence on external systems to generate and maintain your SDK.

In either case, secure APIs or APIs that need specific aspects documented and specific elements obfuscated will likely benefit from the internal build, as this gives you way more control.

What do you think of this discussion? Have you built or bought your SDKs? What was your process like? Let us know in the comments below!