The hard part is done. You built an API for both you and your customers to use. You have started to see some great partnerships from customers and other companies who are using it. Now you want to get the word out about how your API can help people run their businesses more efficiently and help them make more money. Is marketing the answer? It’s a piece of it, but is also comes down to how easy is it for developers to integrate with your API. The answer: Your client API libraries. Designing a client API library for several programming languages can be a great opportunity to encourage developers to use your API. Since your API is part of your product, and your product makes you money, I see a well designed client API library as a money maker. It can allow you to keep current customers happy and find new customers in business sectors that might surprise you. Yet, this is a largely under-appreciated aspect of many businesses that provide APIs. As a part of my startup Affiliate Linkr, I currently integrate with APIs from 5 different affiliate networks, and none of them have a client API library. That’s right, none of them! Talk about a missed opportunity! I wonder how many cool apps could be developed if only they would make it easier for a developer to pull some code off of Github and start innovating. With my experience developing Affiliate Linkr and several other projects, I’ve had a chance to use client API libraries and create some of my own, so I wanted to share my opinions so we can all do a better job creating them. If you are excited about creating a client API library for your API, but would like some help, please contact me on LinkedIn and let’s work together! Here is a list of 13 must-have features when designing your client API library.
Object Oriented Interface
Throw Named Exceptions
Allow Automatic Retries
Should Handle Multiple API Versions Within One Code Base
Base API URL Can Be Changed
Unit Tested and Functionally Tested
Use an Existing Library for Doing HTTP Communication
Ability to Get Raw API Responses and API URL Calls for Debug
Live Demo of Example Code
Library Should be Installable Using a Package Manager
For a detailed look at each of the must-have features listed above, please read on. Object Oriented Interface One of the main reasons you are creating a client API library in the first place is to give people an easier way to work with your API. You want to make it easy for people to create apps using your API, so you gain new customers or make your existing ones even more satisfied. An object oriented interface to your API allows you to fit into the most designs, as almost all developers are familiar with OO and most likely their end application can easily integrate object oriented code. One important detail when designing your object oriented interface is the naming of your classes, class accessor functions and other methods. Your class names should correspond to the different service endpoints. Like if you have a /users/:uid endpoint, you should have a UsersService that returns the user data as a User object. If one of the resources you can access for a user is projects by an endpoint like /users/:uid/projects, you should have a User method of getProjects() that corresponds to this endpoint. Internally, that function could use the ProjectsService class to fetch the data. As with any class, module, or library, make sure you use a namespace so that you do not run into any conflicts with other libraries or existing code. Great naming can help give your API users intuition about how to use your API without knowing all the little details. It is also important to document how this naming will be done. Let’s say that you have an endpoint of /users/:uid/equipment-owned, how would that look? I suggest having a clear naming conversion guide, something that states for example:
dashes and underscores are removed and considered as word separators
camel case will be used (capital letters used for the beginning of words)
get and set will be used for accessors
A naming convention like this would result in the OO method being User->getEquipmentOwned() for the /users/:uid/equipment-owned endpoint. Having a clear naming policy makes your job easier, and also helps future developers implement changes to the client API library easier when the API changes. The specifics don’t have to match what I have said above, but having a clear naming convention is where the value is at. Throw Named Exceptions Your client API library should throw named exceptions for as many error cases as you can. The names of the Exception classes should be self-descriptive, so inspecting an object in the debugger will allow you to have an idea of what is going on. Your exceptions will break down into a few groups:
Make sure to cover them all. They are especially important when a developer just starts to learn to use the library, where onboarding someone smoothly to your client API library can really improve how that developer feels about your company. Yeah, I think of a client API library as a recruiting tool. An example of this would be if the user sets an invalid API key, the API might respond with a HTTP status code or an error data structure. You would present the user with this within your client API library as an exception thrown that would be descriptive and identify the error uniquely, like InvalidAPIKeyException. Having named exceptions are also very important to allow multiple catch blocks to look for specific exceptions by name, so the user of the client API library can integrate error handling into their application. Maybe some Exceptions thrown are fatal to the application, but other Exceptions just require a retry of a request. Having errors that can be recovered by just retrying a request is something that happens to me with a couple of the APIs that I use within Affiliate Linkr. The API errors are random, really have no reason for them, and the same request will return fine with a retry, so knowing what particular error I got can be the difference between a fatal app failure and a smoothly running app. Allow Automatic Retries Not every API is perfect. There could be situations where the API gives a bad response, or is too busy and cannot service a request. Some of the reasons may be out of your control too, like a spotty internet connection that maybe broke down along the way. Having a backup plan for these cases is smart. I suggest to build in a way for the user of your client API library to enable automatic retries. The reason I like it as an option for the user to enable is that maybe the user’s application has a different way they want to handle it. Maybe they want to treat it as a fatal error, and possibly put some analytics on it so they can feed back to the API support team. I feel like adding automatic retries might be better handled in your user’s application in most cases, so whether you choose to have automatic retries as a feature might depend on what your API functionality is. Some APIs might be more prone to errors, or high traffic, where an uncaught error might be common and the consequences could be pretty bad. The essential factors in a retry system is to allow configuration for:
Number of retries
Time between retries
Named Exceptions that will allow retries
Named Exception thrown when all retries fail
Continuous integration capable through online sources like Travis CI directly integrated into your Github README page. It can give a great deal of confidence, but as long as you have clear instructions for a developer to run tests, this is just icing on the cake.
Summary There are a lot of under-appreciated features that go into a useful client API library, but it has to be designed with as much care and attention to detail as the API itself if you want it to be a business driver for your company. If you are excited about creating a client API library for your API, but would like some help designing a client API library using these principles, please contact me on LinkedIn and let’s work together!