Let’s get this out of the way upfront:
Building API helper libraries is hard.
When you think about it, that makes sense. The helper libraries rarely get the same time or attention as the API itself. They’re usually an afterthought. Even worse, most teams are usually only strong in one or two programming languages and dabble in a few others so when you need to support a variety of languages, things get a little.. odd. What you end up with is something often slapped at the last moment written by someone who doesn’t normally code in that language. There’s nothing like reading Python that looks like Java.
First, a library has to be Succinct. My 11th grade English teacher always used the phrase “concise but precise.” A successful library needs to express complex ideas in clear, straightforward ways with as little code as possible. While super flexible libraries provide a lot of power, they introduce complexity which then has to be configured. Ideally, a library should start simple with reasonable defaults which can be overridden if and when necessary.
Next, a library should be Purposeful. Quite often the library is an afterthought and it shows. It’s not well considered in how it’s designed or how it works. A library should be designed just as carefully as the API itself. While a 1:1 mapping of library methods to API calls is good, higher order workflows might make sense to make your users’ lives easier. In my opinion, the best approach provides the structure and functionality to simplify and optimize the most common use cases.
Next, a library must be Open source. While many groups overlook licensing completely or just choose a license like the GPL, they’re making a major mistake. A GPL library introduces ambiguity in how it can and should be used in commercial or proprietary applications. Generally, I recommend an MIT or BSD license to allow the users to do nearly whatever they want. Further, community contributions are great but don’t count on it, especially at the early stages. The organization needs to take the lead to make sure their libraries are fully functional, even if they’re not complete.
Next, a helper library should be Idiomatic to the language. There are few things more awkward than C# written by a PHP developer. This happens most commonly when someone strong in one language writes a helper library for a different language. They don’t adhere to the structures and patterns of the language itself. Being an expert at the API doesn’t necessarily qualify you to write every helper library. Instead you should have an understanding of the language first and the API second.
Finally, a library needs to be Logical. It needs to be predictable. If your library is a 1:1 mapping with the API, it should have a method for every API call. If a method is called “create” on one object, it should be called “create” everywhere it appears. If there are nested resources, you should be able to traverse the objects similarly. Every time you require the user to think and figure out that something is different – or worse, why it is different – you’ve distracted them from their goal.
We have to understand that every awkward, illogical, or confusing thing we introduce will deter some percentage of our potential users.. and most will never come back. Instead, by sticking to these five principles, we can ensure that the helper libraries are as well-considered and designed as the API itself.
At the end of the day, we have to remember our goal: Make it easy to use our API.