This article is for developers who want to build client Software Development Kits (SDK), or are thinking of doing so. If you are working on a technology platform that offers public APIs, it is inevitable that you will get requests to build an API client SDK to help with the consumption of the API. What you read here will help you set up your SDK project for success.
Most developers underestimate the commitment involved. Over the last few years of my career I have worked for two technology platform companies that interfaced over 900+ integration partners and 50k+ developers. I have built and maintained successful client SDKs in various programming languages that are used by thousands of developers. So I have something to say about what it takes to build a good client SDK.
Why Bother Building an API Client SDK?
Has anyone ever seen a technology platform’s developer portal that does not have an SDK? The chances are slim. Most larger platforms have realised that just having public APIs is not enough; they also need to build client SDKs that nicely wrap their APIs so developers don’t have to work so hard on hand-crafting their HTTP calls. This way, developers can focus their valuable development time on building workflows and solutions to solve their users’ problems.
Building SDKs becomes an integral part of the developer experience because they:
- Save huge amounts of development time
- Dramatically reduce “time to first API call”
- Embed optimisation & best practices into API usage
It used to take at least a dozen lines of computer code and heaps of testing efforts just to get one API working. With the help of an SDK, it only takes one line of code. This platform can delight developers … and win the hearts of developers.
Know Your Developers
You may have heard the advice to know your customers (KYC) before you do business. Well, I think before you start building an SDK, you will need to know your developers (KYD). There are many decisions to make before building:
- What programming language to build for?
- What framework to build examples for?
- Are front-end modules needed to help developers render UI? (E.g. Stripe’s React module)
- How efficient does it need to be for a typical production implementation?
- Should there be a mobile app SDK kit?
The best answers will come from your current developers or partners. Call or arrange a meeting with six or eight of them. At the start of an SDK project when you don’t yet have infrastructure for data collection, one-on-one interviews are the next best thing.
The Anatomy of an API Client SDK
An API client SDK’s core components can be broken down into four parts:
- Auth Module
- Data Models
- HTTP Client
- API Client
A finely crafted HTTP client is always at the heart of an API client SDK. This is where the specific settings such as base url, HTTP headers and security mechanism are configured globally. The API client uses the core HTTP client, but loaded with heaps of helper methods such as serialisation of API objects, applying filters, url parameters and deserialisation of responses into API objects.
It should also be loaded with one operation for each HTTP method that each endpoint service has to offer. Depending on how open the API platform is, you will always provide a method for developers to interface with your authentication and authorisation framework (OAuth 1.0 & 2.0 for example) so they don’t have to reinvent the wheel.
Documentation & Sample Codes
Isn’t it annoying to work on a tool that is supposed to be amazing but does not have full documentation? Developers today need to be empowered by good, easy-to-follow documentation. Don’t expect developers to just read everything from the code lines. Spell it out for them! Countless hours are spent creating and testing an SDK. It really makes a difference if some more time can be spared to create good documentation that covers everything.
So does it mean we need to explain every single method in the documentation? Yes, ideally! But there are tools to make the life of an SDK creator easier and automate this tedious task. Check out OpenAPI & Swagger for this.
Sample codes really are quite important for developers to learn about the tool in a practical sense. There are two kinds of samples: a “kitchen sink” sample that tests a lot of API methods; and a starter sample, which covers less APIs but focuses on demonstrating the capabilities of an SDK.
Scale your SDKs with OpenAPI Specification and OpenAPI Generator
I have been around for a few years in IT. I used to work on enterprise systems with SOAP APIs and xmls. In SOAP (not that we are dealing with dirty data), we have something called a WSDL (Web Services Description Language). This is typically a huge specification of what the API models and methods are. The client side can take it and generate what is essentially a basic SDK, regardless of the language or systems they use.
In this day and age, RESTful APIs are the universal language between machines, and a convenient feature such as a WSDL is missing; until the birth of OpenAPI specification, that is. OpenAPI specification provides functionality similar to WSDL. Combined with OpenAPI Generator and templates, it is able to create SDKs automatically, in all languages.This provides a scalable way of creating and supporting SDKs instead of handcrafting each one.
Where I work, these days, one of us can support the development work for two or three SDKs (one for each language) because of the power OpenAPI and the auto generation CI/CD workflow brings.
Continuously Improve, Support & Maintain
SDKs can never be perfect. As soon as developers start to use them, they will encounter issues in their own implementation. So it is important to budget time and resources to continually receive feedback and improvement suggestions that developers provide.
If you intend to run your SDK project as an Open Source Software project. Read my blogpost about Three tips on running a successful open source software project.
It’s like an odyssey, not a drive-through.
Bells & Whistles
Of course, there are other nice things that one can build into SDKs to delight developers. Here are just a few ideas:
- Retries – mistakes happen, build retry logic can help reduce support efforts
- Rate-limiter – throttle the APIs on the SDK, this stops people hammering your API
- Batching – enable it so it makes more efficient API calls
- Paging – building it into SDK helps increase speed of API calls and avoid time-outs by eliminating large response
- Filtering – allows less logic being built by the developer (Again, delighting them.)
Summary
We live in a world where all API platforms are competing to create a greater “magnetism” to attract developer talent. Developers must love your API client SDKs. So get to know the developers first, before building the SDKs. Take the time to write great documentation and sample apps to educate developers. Provide continuous support and improve the SDK by listening to developers’ feedback. The developers will be delighted for sure.
Are you looking to build an API? See 7 Tips for Building an API.
