Better Practices
Published in

Better Practices

To Build (an SDK), or not to Build — that is the question!

If you are building a SaaS product, you most likely also provide an API for your product.

At some point, you will probably consider whether you should also provide your customers with an SDK for the API.

In this article, I will list the advantages of supporting SDKs and the challenges of developing them.

Advantages

The most prominent argument for building SDKs is that SDKs deliver a better developer experience. A better developer experience means higher adoption and usage of the API the company is offering, which means increased usage of the product, which in turn contributes to growth.

The reasons that SDKs offer a better developer experience are:

  • Without an SDK, the developers would have to develop by themselves the functions for calling the API. Such a task is perceived as lacking challenge and mundane by developers, and they would prefer to avoid it (although creating a high-quality SDK has its challenges). In addition, the SDK would have to be maintained to be up to date with the latest API changes and additions, and that’s something that clients would prefer to avoid.
  • In many APIs, a single API call will not accomplish the operation that the developer intends to program — in some cases, more than one API call is required to perform an operation. For example, authentication token renewal — SDKs that are built correctly will be able to abstract this operation, and the token renewal could be done seamlessly, whereas if an SDK would not have been available, then the developer would have to develop a mechanism that can identify when the token has expired and trigger a renewal call before continuing to make the wanted API call.
  • SDKs usually come with documentation that includes examples of how to make certain operations, and developers love examples on which they can rely. They say “a picture is worth a thousand words”; for developers, a single code example is worth a thousand words.

The more your customers use your product’s API for integration with their product, the more likely their satisfaction will increase if you provide them with an SDK, which will lead to more growth.

Challenges

If your product comes with an API and you are thinking about starting to develop an SDK for your customers, then there are some challenges that you must be aware of.

  1. Initial creation and ramp-up time — For each of the languages that you plan to provide an SDK, keep in mind that you will have to build a CI/CD pipeline end-to-end, just as with any service or library that you are maintaining — that will take some time to build and get right: generating or writing the code, triggering tests, updating the documentation for each language and releasing the SDK.
  2. Ongoing maintenance and development — Maintaining SDKs will require more effort than you may imagine. As you release your SDKs and customer adoption of the SDK increases, customers will start reporting issues and bugs which you will have to handle. In addition, you will need to update the SDKs with every API change or enhancement. That’s quite a lot of effort. Just to give you some perspective, mid-sized startups (~100 employees) may have a team of 3–5 developers to maintain the SDKs. In Fortune 500 companies, you might find a group of 10–20 engineers dedicated to SDK development and maintenance. Therefore, you should regard the SDK as another product in the line of products that you are offering and allocate resources accordingly.
  3. Release management — Release management of SDKs is challenging. Assume you provide SDKs to your customers in 5 different languages. Given a new update to the API, ask yourself how do you time and control the release of a new change for all these SDKs? How do you know that all SDKs are ready for release and of high quality?
    End of life is also challenging because you cannot force clients to switch SDKs, and convincing them to upgrade their SDK version is also challenging. So given that you support 5 SDKs and you have released 10 changes to the SDKs (following 10 API updates) then you in fact need to track 50 different versions of your SDKs. Tracking the SDK version used by each client is also challenging once you get to tens of customers or upwards (each one is using a different SDK version for a different language).
    As you may understand, this may get really complicated, and you will sooner or later find yourself appointing or taking on the role of a release manager.

Should you build it?

If your product is an API-driven product, meaning the provided API is at the core of your product offering, a.k.a. API-first product (such as Stripe, Twilio, etc.), then the answer is a definite “Yes!”. As a company building an API-first product, your customers expect you to provide an SDK.

There are other cases where you might not be building an API-first product but you should consider providing an SDK. Such cases are when your product might need a minimal API integration with the customer’s application, such as in their web client, in order to operate correctly, but they are required to perform a series of API operations for the integration. In such cases, not providing an SDK that wraps that series of calls will result in customers spending time with your technical support team, or engineering team, to complete the integration properly. This would lead to customer dissatisfaction and a lot of effort for your support team and your customers.

An SDK will immensely increase the integration experience and preserve your company’s reputation.

Otherwise, do not go for an SDK unless you feel that it is a deal enabler, meaning a prospect will buy your product (preferably writing a big check) if it comes with an SDK for the language of their choice. But keep in mind that once you provide support for one customer, other customers or prospects may follow suit and also ask for an SDK for their language of choice.

Some companies choose to create an open source SDK and release it with a disclaimer saying that the SDK is maintained by the community, but this should be thoroughly considered because not doing any maintenance or neglecting the open source may somewhat affect your reputation as a company.

Finally, keep in mind that in some cases, you can delegate the creation of the SDK to the client by providing a complete and well-structured OpenAPI schema. By doing so, clients can use open source SDK generators such as OpenaAPI-generator to create an SDK for their own use.

Summary

Building an SDK will increase customer satisfaction by providing a better developer experience, and help product adoption.

Providing SDKs has become a standard for companies building API-first products.

Building and maintaining SDKs requires considerable effort, and any company which does not build API-first products should thoroughly assess the cost-effectiveness of building and supporting SDKs.

Feel free to share any tips or tools you have learned from building SDKs in the past in the comments.

Thank you for taking the time to read this article. I hope you found it helpful. If so, show your love and add some claps.

Follow me for more articles about team building, software engineering, technology, and technology-enabled business opportunities.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Shahar Davidson

A startup engineering manager — writing about startups, team building, management, tech, and how tech enables business.