Choosing an API for your new project is a lot like marriage.

Why ?

Because the right choice can significantly improve the quality of your software. On the other hand, a wrong choice has the potential to ruin your software or make maintenance costs go through the roof. Also, divorcing an API can be super expensive, frustrating and time consuming. Given below are 9 red flags I usually look for before being lured by the siren of brand new APIs.

1.Not having clear or prohibitive licensing requirements

Licensing restrictions can severely affect the distribution and sale of your software or service. It can also force you to disclose your intellectual property / source code.

For example, Open Source APIs Licensed under GNU General Public License (GPL) requires you to release any derived work under GPL as well. This implies that if you use a package licensed under GPL in your program, you need to release the source code of the program as well . For many companies developing intellectual property , this is a deal breaker. If going with open source, it’s almost always better to use the more permissive GNU Lesser General Public License(LGPL) which allows you to use and distribute the open source software with your application without releasing the source code for your application.

That’s a lot of legal mambo jumbo. If your company is large enough to have a dedicated Legal department, I’d highly recommend involving them in these decisions. In case of Microsoft, it’s actually a requirement to run any open source project incorporation through Legal before use. If your company does not have a legal department to help with deciphering the licensing implications, here’s is a page that explains the various open source licenses for mere mortals: http://choosealicense.com/licenses/ . If you’re feeling more adventurous, you can also read about various open source licenses available at https://opensource.org/licenses .

 If you’ve found a piece of software/ API on the net that does not have any licenses attached to it, you probably should not incorporate it into your product without a IP Lawyer’s supervision.

2. Having high or undisclosed maintenance fees

Most of the time when people think of buying a piece of software on disk, they think it’s a one time expenditure. We tend to associate ongoing subscription fees only with cloud based services. That may not always be the case.

The API you just purchased might require you to :

1. Pay an annual/semi-annual cost for as long as it is used in your software
2. Pay a fee based on the number of copies distributed
3. Pay for any consulting fess / support you need on the API usage
4. Pay for any patches, bug fixes or design change requests you make to the API vendor.

All these things above means that the operating cost of your software (or maintenance  cost) is going to be higher than you initially anticipated. So, it’s critical that these questions are answered upfront and the costs factored into the lifetime cost of the software.

3. Not having good documentation

The point of having an API is to abstract away the implementation complexities from the user of the API. If you cannot figure out the API usage easily from its associated documentation, you effectively have a few choices:

a. If the API is open source, dig through the source code to figure out the correct usage

b.If it’s a commercial API and source code is not available,

1. Find out the correct usage experimentally by trying the API in isolation using various inputs
2. Call support

All the above ways of figuring out the API usage costs a lot of time and effort. Wouldn’t you rather be focusing on your business logic rather than spending time to figure out API usage ?!?

A well-documented API should have the following characteristics:

1. An API documentation should not assume that the user of the API is familiar with the underlying standards using which the API is built. If necessary, it should explain the few necessary details in place. For example, to use https, an API user does not necessarily need to know the details of TLS/ SSL and the API documentation should not force them to read up on those).
2. In addition to documenting the input and output of API functions, also state the effect of making that API call on the state of the system. That is, what is the downstream impact (Idempotency etc.) , if any, of calling the API.
3. The API documentation should have code snippets and sample usage of each of the API functions. Your programmers should not have to dig through unit tests to figure out API usage.
4. THE API documentation should have a Getting Started guide that should walk someone through a complete scenario step by step and without making any assumptions.
5. The API documentation should be up-to date with the latest version of the API. It should also keep archived versions for previous releases in case you choose to not upgrade your clients.

Here’s a great example of an API that meets the above criterion: http://pocoproject.org/documentation/index.html

And here’s an API documentation that leaves a lot to be desired: https://qpid.apache.org/releases/qpid-proton-0.13.1/proton/c/api/messenger_8h.html (To be fair, qpid proton is a very powerful and useful API – but getting up to speed on this took a long time because of the lack of documentation).

4. Not having access to source code

This might seem like a contradiction to point #3 above – but it’s not. You should not have to read the source code to understand the API. However, sometimes, it might be critical to have access to the source code to understand, optimize and fix some critical issues.

War Story: Back in the days when we still shipped software on CDs, I was working on a version of Microsoft Search Server. We wanted search to be available in 42 languages. Internally , we had developed language parsers for around 20 of these languages and purchased the rest from a vendor company in Eastern Europe. The API/ components the vendor company gave us was pretty solid functionality wise. It passed through the validations fine. A few weeks before shipping, one of the devs using the component reported an AV during his security tests. When we started taking a closer look, we suspected these sort of vulnerability might exist in the other procured components as well. So we set up around 80 machines to do distributed fuzz testing of the components …. It was a nightmare. There were AVs popping out from many of these components like candies falling from a piñata.

          We contacted our European subsidiary who had procured the components  to contact the vendor for a fix. It turned out that six of those components were purchased by the vendor from another company who’ve since gone out of business. We asked for the source code to fix the problems ourselves, but they did not have it. At this point, we were left with no choice other than disabling those features in the six languages. Luckily, Microsoft has a separate division that does Natural Langguage Processing and they helped us develop those components inhouse shortly after release and we were able to patch the systems to enable those features.

So, the morale of the story is that you need to have access to the source code when procuring APIs/ Components from vendors who might have a chance of going out of business. Now, some reputable vendors might not give you access to the source code – and that’s fine as long as you have confidence in the continuity of the vendor and have the right support agreements in place.

5. API is not thread-safe(no support for multi-threading)

In today’s world, it’s hard to imagine a piece of software that is not multithreaded or at least thread-safe. Even if thread safety is not required by your client initially, you never know when they’ll change their minds and ask you to provide thread-safety as a feature.

If the API you choose is not inherently thread safe or does not support true multithreading, you’ve coded yourself into a corner. At this point, your only option is to create some threadsafe wrapper APIs on top of the non-thread safe API you choose initially. However, this solution will likely be not as performant as you’ll need to serialize access to the non-threadsafe APIs at some point via some synchronization primitive (mutex, critical section). The situation of your software pipeline is represented below when this situation arises.

Note that the incorporation of a single threaded API in an otherwise multithreaded environment creates a bottleneck that cannot be resolved.

6. Not having a large enough adoption

No matter whether you choose open source or commercial APIs, in 99% of the cases you’ll need to google information for the API online when you get stuck or hit an error. At that point, unless a lot of people are actively using the API and discussing them on sites like www.stackoverflow.com , you’ll be stuck banging your head against a wall for a few hours to days. By using an API with large adoption, you can short circuit the head banging process. Just like high school when it paid to be part of the cool group, it’ll pay off to use an API that’s popular among developers.

Additionally, a large user base means that the API has probably been hammered enough to weed out the critical bugs. So the chances of you or your customers hitting these bugs is inversely proportional to the adoption of the API.

In my experience, it’s almost never a good idea to be an early adopter of an API, especially if you’re shipping commercial software. Even if you really like the API, give it some time to mature before sticking it in your software.

7.Not having a dedicated team supporting it

This is more relevant for open source software than commercial software. In many cases, you might find a piece of open source software that fits your immediate needs. But it might turn out that it’s only maintained by a few individuals on their spare time and quite infrequently. This can cause a problem for you down the road if you need to get a bug fix or a design change request. Without people who’re actively triaging bugs and creating fixes / updates to the API, you’re stuck with either working around the bug in some hacky way or fixing the bugs in the API yourself. Both are time consuming, risky and does not directly contribute to your ROI.

A quick way to find out is to join the user-group/developer dl for the software and look at the bug filing and resolution history. Monitor the frequency of the user support requests going through the DL and see how effectively they are resolved. Then make your call.

8.Not having backward compatibility between existing versions of the API

If you’re shipping a piece of software that’s intended to have a shelf life of more than a year, it’s very likely that you’ll need to provide updates for bug fixes or to light up new features. At that point , you might need to take dependency on a more recent  version of the API you’re currently using. If the future version of the API is not backwards compatible, you’ll be stuck using the older version. You can always rewrite pieces of your software to make them compatible with the newer version of the API, but that will cost you and can inject risk and stability issues into software your customers are actively using.

So before you select a piece of API, check the backwards compatibility between the various released versions. If the API vendor has a history of breaking compatibility, avoid that API like plague.

9. Not being platform independent

If the core of your API relies on platform specific functionality, it’ll be very difficult for you to port it to other platforms. We’re in this boat right now for one of our APIs where a large chunk of the parallel processing code relies on PPL( Microsoft Parallel Patterns Library). Porting this code over to Linux is going to be extremely time consuming. On the other hand, if we had written our API using standard C++ async , it’d have been a much easier port.

So even if you’re planning to ship your software on one platform, don’t get locked in a situation where migrating to another platform will need a re-write of the system. Try to select an API that uses standard facilities of a language as much as possible instead of using vendor / platform specific functionalities.

So should I choose Open Source or Commercial APIs?

                 This should be determined on a case by case basis. As far as I’m concerned, I tend to gravitate towards commercial APIs from reputed vendors that exhibits the nine criterions above over open source APIs. I put a lot of value on stability and accountability. When you’re buying a commercial API with a support clause, it is legally and financially binding. There is usually a Service Level Agreement (SLA) guaranteeing specific turnaround time for bug fixes and support requests. It ensures that developers on my team can focus 100% on the business problem we’re trying to solve instead of figuring out the nuances of a specific third party component. But then again, this is based on my personal experience using both open source and commercial APIs – your mileage may vary 🙂

 Have any additional thoughts on API design? Please leave your comments in the section below.

Please share if you liked the article