What is an API client library?
Client libraries are sometimes called helper libraries. What are they and how do they help developers use an API?
Over the past year I’ve run a few workshops on API Technical Writing. Part of the workshop content is about client libraries, and I decided it’s worth discussing this topic in a blog post too. It’s of interest to technical writers who are documenting APIs, particularly web services and REST APIs.
What is a client library?
A client library, sometimes called a helper library, is a set of code that application developers can add to their development projects. It provides chunks of code that do the basic things an application needs to do in order to interact with the API. For example, a client library may:
- Provide boiler-plate code needed to create an HTTP request and to process the HTTP response from the API.
- Include classes that correspond with the elements or data types that the API expects. For example, a Java client library can return native Java objects in the response from the API.
- Handle user authentication and authorisation.
How is that useful?
Looking at the developer who’s using the API: With a REST API or any web service API, the developer could be using any of a number of programming languages to make the API calls.
Wouldn’t it be great if we could give them some code in their own language, to help them get started with the API? That’s what a client library does. It helps to reduce the amount of code the application developers have to write, and ensures they’re using the API in the best supported manner.
Examples of client libraries
In some cases, the API developers provide client libraries for the API. In other cases, client libraries are developed and supported by the community rather than the API developer.
For example, here are the Flickr API client libraries listed by programming language, all maintained by the developer community:
- flickr-net for .NET
- flickgo for Go
- flickrj for Java
- flickcurl for C
- node-flickrapi for Node.js
Here are more examples of client libraries, listed per API:
- Twilio API (an impressive number of client libraries)
- Google Calendar API
- Google Maps web services
Is a client library the same thing as an API?
No, although they’re closely related. My post on API types describes library-based APIs, which are libraries of code that developers need to import before they can use the API. So, how does that differ from a client library?
Here’s how I see the difference between library-based APIs and client libraries:
- Library-based APIs are those where the developer needs to import or reference a library of code or binary functions before the application can interact with the API. For example, the documentation for the Google Maps JavaScript API describes the HTML <script> element needed to load the API library.
- Client libraries are additional libraries of code that are provided to make a developer’s life easier and to ensure applications follow best practices when using the API. In general, you can call the API directly without using the client library. (In some cases, though, the client libraries may be the preferred or even the only supported means of interacting with a particular service.)
I’d love to hear your thoughts on this topic – does the above summary make sense, is it useful, and what have I left out?
Posted on 25 October 2015, in APIs, technical writing and tagged API documentation, api technical writing, APIs, client library. Bookmark the permalink. 12 Comments.
ffeathers 
Nice article, at just the right level of detail for API-focused technical writers, IMO. Since you asked for comments:
* It’s important to understand that it’s possible to write directly to the HTTP API, so client libraries are almost never strictly required, but they’re often much more convenient to work with. Not sure that point is made explicitly here.
* In “What is a client library?” the first bullet point explains that it provides “boiler-plate code” to invoke a request and process the response. It’s not just the extra boilerplate code you have to write, it’s about translating an asynchronous, event-driven HTTP protocol into a (usually) synchronous method call that is more natural to the application programming environment. It might be useful to compare a code example written directly to HTTP, vs. an example that uses a client library.
* Client libraries are often generated, wholly or partially, from API description languages like Swagger, API Blueprint or others. It might be useful for technical writers to understand that this is part of the value chain, and another reason why API description languages are useful.s
Thanks again for posting! Cheers,
– Ted
Hallo Ted
Thank you for those valuable additions! In particular the second point is something I hadn’t considered. I’ll take a look around for a code sample that writes directly to a REST API, and one that uses a client library to interact with the same API. That’s a great idea for a way to bring the concept of client libraries to life in a post like this.
Cheers
Sarah
Is it fair to say that if you have API documentation, and you have a client library, that you have an SDK? (Maybe not that much of an SDK, and it would be better to have sample code too.)
Hallo Lois
That’s an interesting question. The term “SDK” can mean many things. I don’t think it’s true to say that API docs plus client library = SDK, though.
The difference between and SDK and an API, as I see it, is the following: An API is something you use to communicate with another application or service. An SDK is a collection of tools, which may include libraries of code but does not necessarily communicate with another application. The code libraries in an SDK may provide nifty routines to do things like compute complex formulae, for example. An SDK can also provide tools for debugging an application, and things like an emulator for a particular device or platform, so that developers can pre-test their apps in the emulator before needing to install the app on a real device.
I hope this helps!
Cheers
Sarah
Hi Sarah, A good SDK will have what you mentioned. I guess it becomes a semantic question as to when you can still call the bundle an SDK when there’s practically nothing there :).
This column brings up an issue that’s very near and dear to our hearts at ProgrammableWeb.com. As you may (or may not know), we run a directory of APIs.. arguably the largest and most relied-on of its kind. But what a lot people don’t know is that we also track other types of “assets.” Under the hood, APIs are in one table and then, in another, we’ve got SDKs, Libraries, and Frameworks grouped together. But this data model isn’t holding up to the evolution of the API economy.
First, to @Lois’ point, there’s the vernacular problem. What one person calls an SDK, another person calls a Library. One visit to Github is all it takes to see this issue in spades. So, in the spirit of evolving our data model in a way that best supports developers, I decided to take a stand on this front. Developers almost universally interpret “SDK” to mean something that makes it easier for them to consume a service, API, capability, etc. So, regardless of whether someone calls their technology an SDK, a client, a client library, a binding, a library, …. if it’s designed specifically to ease the consumption of an API or something like it, it’s an SDK and we’ll record it as such in our database. A library, on the other hand, is similar to an SDK in that it’s usually platform specific (iOS, Android, Python, Ruby, Node, etc.), but it is not oriented around consumption. For example, we’ve cataloged many libraries that are for standing up APIs. And, in my mind, frameworks are on par with platforms. For example, we see many libraries that are specific to a language like Javascript, but run on top of a framework like express.js — almost as if express.js were the platform (even though node is underneath).
Now, I realize that not everyone is going to agree with this view. But it is a view that fits the API-context that ProgrammableWeb operates in and it gives a basis to address the second problem which is how organize these assets in a way that they’re easily discovered on ProgrammableWeb by developers who are just looking to find what they need and get on with developing. For example, developers these days are more inclined to work with an SDK versus the underlying API (if there is one). So, in a new model, SDKs, Libraries, and frameworks are not grouped together. They each get a separate table with fields that are more specific to their purpose. For example, the SDK table has a field that joins it with the API database in a way that a search for the API will get you all the related SDKs and vice versa. One reason this is important is that independent developers are out there building SDKs for certain APIs without the knowledge of the API provider. For example, API providers typically don’t bother publishing an SDK for Haskell. But developers who love Haskell might fill that gap and make the source available as open source on Github. We’ve seen APIs for which there are 3-5 SDKs in one language alone! Maybe one from the API provider and a bunch of others from independent developers. Developers should be able to discover these SDKs very easily.
Going back to one of @sarah’s points, some SDKs abstract APIs that developers could otherwise work directly with and some don’t. For example, Evernote does not have a RESTful API that developers can interact with directly. The only choice is to pick one of their SDKs which are automatically generated by Thrift, the Apache technology (originally from Facebook) that Evernote picked to underly their “api strategy” [sic]. From a data model perspective, this creates another challenge if you’re us (ProgrammableWeb). If there’s no actual API, and there’s a relationship between our API and SDK tables under the hood, then what happens when developers search for the Evernote API (technically, something that doesn’t exist). How do you lead those developers to the SDKs?
David Berlind
Editor in Chief
ProgrammableWeb.com
Hallo David
Thank you for all this info! It’s very helpful seeing the world of APIs from the current and evolving perspective of developers, and of ProgrammableWeb in particular. I did a search for “evernote api”, just to test how well your data model is working. 🙂 My first 2 hits were the Evernote developer docs (https://dev.evernote.com/doc/) and their developer site’s home page (https://dev.evernote.com/). The third was ProgrammableWeb (www.programmableweb.com/api/evernote). I guess your phantom API entry is working well!
I like the idea of merging the concept of client libraries with SDKs in your data model and in general tech writing terminology. The merge is happening anyway, and it’s good when our models reflect the real world. (If something as meta as a client library can be called the real world.)
The description of a plain old library sounds good too. I’m not sure what you mean by “standing up APIs” in this bit:
“A library, on the other hand, is similar to an SDK in that it’s usually platform specific (iOS, Android, Python, Ruby, Node, etc.), but it is not oriented around consumption. For example, we’ve cataloged many libraries that are for standing up APIs.”
But the gist is clear.
It’s interesting that most developers prefer to work with an SDK rather than the raw API. I’ve been getting that impression too, from chatting to people. Do you have any thoughts on whether developers are making themselves vulnerable to SDKs that may not be maintained in the future to the level they’d expect, how developers validate the maintenance prognosis for an SDK before choosing it, and how much work it is to swap to a different SDK if necessary?
Cheers
Sarah
That’s an interesting point (among many here). There’s already some vulnerability in building your application on the basis of an external API, because you don’t know what will happen to it. If you are paying for the external API, you at least have that agreement with the provider. If you are not paying for it, then the external API provider can (usually) change the terms. With an external SDK from yet another provider, you are compounding that vulnerability.
thanks..
Pingback: API Digest #31: Practical Tips on How to Code APIs Better and Faster
Pingback: The trouble with client libraries – colum Walsh
Pingback: API Integration – What is it? The Definitive Guide - { DreamFactory: 'Blog' }