How To Choose an API That Works For You

Eran Galperin is the CTO of Binpress, a marketplace for commercial open-source projects. As part of its goal to evangelize the use open-source professionally in business and enterprise, Binpress also hosts a large amount of API wrappers, libraries and SDKs.

We live in the age of the API. Almost every self-respecting Web Service today provides some kind of programmatic access to its data and/or facilities. APIs range from location-based data to online payment processing and everything in between.

Not all APIs are created equal though. For any specific task you can likely find multiple competing APIs that use different approaches and provide varying levels of Documentation and support – all of which you should take into consideration when picking which API to use.

What to Consider When Picking an API

Picking the wrong API provider could be a major time-sink or worse – it can create vendor lock-in that is hard to break out of (think payments APIs). In some cases you would be marrying your application to the capabilities of a specific API – so making the right decision is critical.
When comparing APIs and trying to determine which is right for you, there are several things to consider:

  • Feature Completeness: Does this API do everything I need it to? Don’t assume that all similar APIs provide the same calls and processes. The Paypal API, for example, provides an authorize-capture process for funds – while Stripe does not. (Note: Stripe has since added this process, though it was not previously available). Know what features are required for you and filter your selection based on that.
  • Documentation: How comprehensive is the documentation? Are the examples clear and all the parameters properly explained? You can also get a glimpse of how an implementation would look like from the documentation (and if not – that’s a big red flag). Which brings us to the next point:
  • Data Formats: 10 years ago XML was the king of programmatic request data format. Since then, JSON has emerged as a much lighter and easier-to-use alternative. Some APIs still return data in a URL encoded string. Which do you prefer to use? What do your prospective APIs provide?
  • Interface: Browse through the API documentation and look at the method and parameter names. Do they covey their purpose clearly? Do they fit your personal taste in naming conventions? Touching again on the Paypal API, the ALLCAPS, no separator / whitespace parameter naming really hurts my eyes. (To be fair, Paypal has recently launched a new version with lowercased, underscore separated parameters). Some API providers today try to be clever and require the usage of custom headers and HTTP verbs that are not trivial to program against. That might be right up your alley, or might be a pain in the ass, depending on your point of view.
  • API Limits: Many APIs, especially those with public facing data, employ a request threshold per API Key or IP. Those limits are in place to prevent abuse or in some cases motivate you to upgrade your account, but from a developer’s perspective they add complexity and overhead. Now you need to manage your request rate and make sure you are not hitting the API limits. Is this overhead worth it to you? Are there competing APIs that offer higher limits or none at all?
  • Language Support: Depending on the complexity of the API, having ready support for your programming language of choice in the form of an SDK or example scripts, could be invaluable. Existing libraries save you time – both on development and debugging. Lack of language support increases the onus on having superb documentation since you will be developing against it from scratch.
  • Community & Support: When things go wrong, you will need someone to answer your questions. Whether it’s regarding API limits, broken requests, timeouts and everything in between, there are things that only the API provider can help you with. Does the provider have support forums? Is the community helpful and active? What is the provider’s reputation for answering support questions/tickets in a timely and relevant manner?

Planning for Change

Even if you go through the entire checklist you still must prepare for the fact that APIs and your product will evolve and change in ways you can’t predict. How do you interface with an API today in a way that won’t cripple your product tomorrow?

ABA – Always Be Abstracting

To protect against change, you should always have a layer of indirection for interacting with an API. If you are handling payment data then you should pass off your generic payment information (customer and address details, payment method, charge amount and description, etc.) to an API wrapper class that can deal with it internally and make the call to the API provider. In the same manner, your application code should not deal directly with API responses, but with normalized data returned by the API wrapper.

In cases where you need to switch providers or switch to another API within the same provider, having a layer of indirection and some forward thinking could save you A LOT of time and anguish.

When using a Library or SDK provided by the API provider or community, it is my rule of thumb to always have my own abstraction in front of it, as those libraries typically talk in the language of the API (i.e, specific API flows or methods). Having this additional layer of indirection in front of the API library should lead to reduced switching costs and simpler interfaces to work against.

In the API We Trust

Picking an API can be a major commitment depending on the scope of Integration and the services it provides. At the same time, many APIs give us access to data and processes that are otherwise not accessible without a huge time investment and capital.

As Uncle Ben once said, “with great power comes great responsibility” – do your due research ahead of time and use indirection to interact with the API to minimize your risk while harnessing the power offered to you by API providers. See you in the cloud.

Be sure to read the next Best Practices article: API Developer Outreach Checklist