Client libraries are one of few ways to dramatically improve Developer Experience (DX) for your APIs. However, with all the programming languages your developers use, creating client libraries can be quite a challenge — and that’s not to mention the maintenance that comes with every update to your APIs.

What if you could reap the rewards of client libraries with a fraction of the effort? That’s exactly what novel automated library generation tooling hopes to achieve — but does it really work? In this article, we’ll teach you everything you need to know about client libraries: what they are, whether you should automate the creation process, and how to get started.

What Is a Client Library?

Let’s start with the basics: “what is a client library?” In short, a client library is a collection of code specific to one programming language that makes it easier to use an API.

See, almost all web APIs communicate by means of HTTP, and pretty much every programming language supports HTTP. However, the way we make HTTP requests and process HTTP responses can vary wildly from one language to another, as can the data types available to us. This results in the need for developers to create a custom implementation of our API based on the programming language they’re using.

Client libraries codify API requests and authentication processes as if they were native functionalities of the given programming language. What’s more, client libraries automatically format API responses to match the data types used in the programming language. Together, this vastly decreases the amount of time developers need to get started with using an API, while also reducing the likelihood that something will go wrong.

All in all, client libraries make for a better Developer Experience. And what with the growing relevance of DX, client libraries are now considered a staple addition to any API.

Why Bother with Automation?

Why bother automating client library creation? For starters, one library certainly isn’t enough. APIs often offer multiple client libraries for many popular programming languages. After all, a client library is only any good for developers if it’s written in the language they want to use.

We realized no one would want to handle tokenized file uploading in an unfamiliar language. Just because they’re developers and they’re extra smart, it doesn’t mean they want to work extra hard. They’re looking for the path of least resistance — they want to move that task into the Done column.

The other reason you’d want to automate the generation of client libraries is to ensure they’re kept up to date. An outdated client library is no good. In fact, it’s probably better to have no client libraries at all than to have outdated ones. While you can most certainly update libraries manually, it takes a lot — and we mean a lot — of time to do so. At Kaltura, they found that with every update to the API, more than 40% of developer resources were used on updating client libraries alone.

Although it may take a fair bit of effort to set up automated client library generation, it immediately solves both problems. With an automated system in place, you can create client libraries for as many programming languages as you want, and, as often as you want.

Ultimately, you’ll be able to effortlessly update all of your client libraries with every update to your API — and there’ll be no worrying that you’ve missed something.

Tooling for Client Library Generation

If you want to automatically generate client libraries, the easiest place to start is with some kind of an API specification, which defines all of your endpoints, authentication processes, and more.

There are a number of reasons why you should be using a specification, and there are a number of great specification formats out there. Undoubtedly, the most popular specification format is the OpenAPI specification — formerly known as the Swagger specification. If you’re using OpenAPI, you can very easily generate client libraries with a tool like OpenAPI Generator or Swagger Codegen.

Things get a little more difficult if your API is particularly complex. As Avital mentions, generated code tends to impose constraints, and constraints tend to result in poor developer experiences. While automation is generally a good thing, you definitely need to watch out for such incongruities.

Generating Code Libraries From A Schema

At Kaltura, they decided to start with an XML schema that details the API’s functionality. Then, they created a generator which could parse an XML schema and spit out client libraries.

The complete process takes their server logic — in other words, the API — creates an XML schema, generates client libraries from that schema, and puts them onto GitHub for testing. All client libraries which pass the tests are automatically pushed into a public repository.

The best part of this, Avital says, it that the process repeats every night, generating an XML schema from the API and then the client libraries from that schema. As such, the libraries are always up to date.

Currently, Kaltura uses generators written in PHP to create client libraries in Java, PHP, Python, Node.js, Angular JS, C#, Ruby, TypeScript, Swift, and others. For each new language they want to add, all they have to do is write another PHP generator — which Avital says is “super simple.”

As for the rest of us, well… Kaltura has made their API client library generator an open-source project! It allows anyone to write their own XML schema and automatically generate client libraries at the push of a button.

Final Thoughts

All things considered, it makes a lot of sense to automate your API client library generation. While there are quite a few tools for generating client libraries from an OpenAPI Specification, they might not work for very complex APIs. At Kaltura, they ultimately decided to create an XML schema for their API, and build their own tooling to generate libraries from that.