Things to know before you build SDKs (Copy)
Application developers today are faced with the burden of choice. Having to pick the libraries, software, frameworks and toolchains to build applications is nothing short of tedious. If you’re a SaaS business competing for a developer’s attention, it’s easy to see that the tedium of picking and playing around with software that you use to build your app, will deeply affect the developer’s choice of what goes into their app. Enter libraries/SDKs and build tools.
The easiest way to allow developers to programmatically integrate your offering is to ship an accompanying SDK with your offering. SDKs are a typesafe way for developers to understand the contract of your SaaS APIs.
Why ship wrapper SDK
[Onboarding] SDKs improve the onboarding experience drastically, reducing the need to read documentation related to parameters, return types, quotas and quality of service. This is a natural recipe to improve conversions
[State Management] API interactions inevitably become stateful, requiring your customers to mediate state between your own APIs. SDKs save them trouble by managing the state for them, and providing higher level APIs.
[Reduced opex] Faulty integrations tend to be a massive operational expenditure for APIs startups. These are particularly hard to correct, since it is often hard to tell apart intentional spam from inadvertent abuse. SDKs allow you to control the narrative and ensure your software is used the way you intend to.
[Reduced cost of migrations] As you evolve your product offerings, customers will need to migrate to newer versions of your APIs. A versioned SDK, whose coordinates can be bumped up with a keyboard shortcut, is a far superior upgrade experience in comparison to having to read release notes and hoping for no breakages and sufficient test coverage.
So should you just go all out and build SDKs for your APIs? It depends. SDKs are expensive. I’ll cover some details on what the development and maintenance costs of SDKs are and how some of these costs can be reduced in the sections below.
SDKs have a high quality bar
The way SDKs are distributed, two adoption cadences determine when the software is actually deployed. Developers need to adopt a version of the SDK, rebuild and ship their application, and in the case of mobile apps, end users will need to upgrade their applications. While this has the desirable trait of being an organic slow roll out, it also means that bug fixes take as long to get fixed. Particularly in the case of native mobile applications, there’s no easy way to bypass these release cycles without seemingly bypassing the App/Play Store and being at legal risk.
Keeping up with the ecosystem
SDKs distributed to customers run in untrusted, heterogeneous environments. Customers may include SDKs into their apps in non-standard ways that involve variable build tools, build operating systems, dependency graphs etc. A large part of building a robust SDK is to ensure that these variables are accounted for. Developers using the SDKs should be able to reliably build their apps and target them onto the desired platforms. End users should be able to reliably use the app without being subject to any quality issues attributable to the SDK.
Accommodating such variables is not a one time cost. The heterogeneity of the build and deployment environments means that there is the constant cost of having to “Keep up with the ecosystem”. The release cadence of your SDKs will need to accommodate external ecosystem needs, in addition to serving your product release goals. For example, breaking changes introduced by any of these variables will often need the SDK to be rebuilt and distributed, even if there are no other accompanying features shipping, just to make sure customers can continue operating their apps.
There’s more to cover about this specific topic, that I’ll cover in a separate post.
Supporting multiple languages
The costs of keeping up with the ecosystem mentioned above rises nearly linearly with each increased language or integration environment. Here’re a few things to keep costs down, while supporting multiple integration environments
APIs that are REST based will help avoid having to handcraft all your SDKs and instead autogenerate your clients as you evolve your APIs. While you may sacrifice aesthetics in the process, this can be an excellent option to reduce maintenance costs. Several teams at Google use Gapic.
It’s imperative to arrive at a prioritization between different surfaces. For example, you may find that your primary “Gold” surfaces are Node, python and Java. Go, Rust, Flutter (extensions), React (extensions) are the secondary “Silver” surfaces.
Secondary surfaces can be auto generated clients, while primary surfaces are crafted by hand. Secondary surfaces may also be maintained by temps or contractors, and their release cycles can succeed the primary surfaces that remain strictly up to date with your product offerings.
Open source your SDKs. Customers that need support for unsupported surfaces will thank you.
I’ll talk about some best practices and operational excellence in client SDK management in a separate post. That’s all for now.
