Our developer experience team at Lob is small but mighty. And when I say small, I mean a single-digit team. Though our team structure has been rapidly evolving since last summer, our commitment to an excellent developer experience is unwavering. So when I say mighty, I’m referring to the fact we released seven Software Development Kits last year. How did we do it?
TLDR: Despite a few hurdles, we highly recommend OpenAPI to generate your SDKs to take the heavy lifting out of putting out quality code in a reasonable time frame.
A software development kit (SDK) is essentially a collection of tools and software in a single installable package. If we think of an application as a house, and an API as the communication between houses, then an SDK can be thought of as the foundation each house is built on. They serve one purpose, and that is to have an out-of-the-box experience on which an application is built.
SDKs are important because they accomplish the one thing that every developer wants: to be lazy.
Imagine this, you're a C# developer, and you have the incredible idea to automate your wedding gift thank you letters. You could go searching for an awesome print & mail API that is written in Node, check out the documentation, write your models for each letter, write out your HTML template, and then finally send those letters. Alternatively, if you are familiar with Javascript, you could spin up a quick application and communicate directly.
Or, you could just grab the C# SDK from Nuget and write your HTML templates—done! Leaving you more time with your wife and new family. After all, laziness is just another word for efficiency!
This goes hand-in-hand with the above because we developers are, to put it more kindly, efficiency-oriented. We desperately want to avoid boring stuff we have done a million times. When we make a change to the API, we don't want to have to write documentation about the change and then write the implementation again over and over—seven times. Then write tests, and more tests…times seven. With no patience for this type of endless repetition, and in our case, limited resources—ain’t nobody got time for dat.
What OpenAPI allows us to do is make a change in one place, at one time, and generate all the changes in each language.
OpenAPI uses templates written in handlebars and mustache to both generate your docs and now your code! Furthermore, most companies have adopted tools like Swagger and Redocly to write their documentation using specs. The secret is, these same specs are nearly identical (and sometimes completely identical) to the specs needed to get started with your SDKs.
Our goal in 2022 was to reboot our SDKs. They were old, needed a lot of love, and we wanted to support additional languages—for example, we had no SDK for Typescript, Go, or C#.
We were already utilizing Redoc with a spec to generate our API documentation, so we created our first test repo with OpenAPI. Then we had to figure out how to actually use the OpenAPI generator; this was even easier than expected. OpenAPI has some excellent documentation and more integrations than you can shake a stick at. We opted to use the pre-designed Docker image and began our journey.
We tackled a brand new SDK first: Typescript, then moved to an overhaul for Java, PHP, Python, and Ruby, then took on two more new SDKs: C# and Go. While some of these languages were totally new to our developers, working with OpenAPI shortened the learning curve. This is not to say it was all sunshine and rainbows.
The main issues we faced when generating SDKs came from our spec. If you use "anyOf", "allOf", or "oneOf" in your spec, then you will quickly find that in most languages (especially strictly typed languages) you will have some major problems.
With Typescript it was simple to write a quick change to the template that allowed for union types. Unfortunately, the moment we started working with Java, we realized this simple change was going to be a thorn in our side.
While I will spare you the details of our full implementation, I will just say we used polymorphism in our constructors to change everything to a string, then just sent that string along via the API in the back end. On the spec side, we separated the doc spec from the SDK spec and just removed the problems one at a time. This allowed us to just flag certain things (i.e., isOneOf) and handle them differently in the templates.
Because we continue to augment the functionality of our APIs, we are constantly revisiting each SDK. While we run into the occasional challenge with a finicky language (I'm looking at you, Java), the ability to automate changes across the board drastically improves our velocity.
Despite these speed bumps and limited resources (we ended the year with only 1.5 developers), we are ringing in the new year with seven fully fleshed-out SDKs; you can check them out on GitHub:
Cheers to Sid Maestre, Matthew Jackson, Aditi Ramaswamy, Makeda Davis, and Jessica Ho—without you this could not have been accomplished. And of course, let’s raise a glass to OpenAPI; without it, this would not have been possible.
