What Causes an API to Fail?


Over the years we have been asked by many people why their APIs have failed. While it is difficult to get into the nitty-gritty of each individual case, there are a couple of general reasons for the failure. Sometimes an API does not even take off beyond the development cycle or the beta phase. Most of the times it is poor marketing that led to the API never actually taking off. As an API designer online it is important to have the ability to control all if not most of the factors relating to your API which will merit its success.

Failure to Add Version Numbers

Yes! We know what you’re going to say, but even something so basic can cause confusion which leads to failure. Many times the API will fail because developers have no idea of its version number. Also, the perception is that if the API does not have a version number, then the developer will not support it. So, any bugs that are found will never be fixed. Adding a version number to your API will cost you nothing, but it is a confidence booster for developers who want to implement it. Similarly, it is essential to support the API.

Almost no developer in the world wants to one day wake up to find out that the API’s entire design has changed. Since once software is out hundreds if not thousands are relying on the API and if it breaks, that’s thousands of unhappy users. So, make sure to use a version number and respond to developers.

Using XML Instead of JSON For Coding

XML has been the development language of choice for API developers for quite some time now. It is by far the best language for API development. However, those who developed APIs back in the 90s would remember XML was considered the best for coding.

error handling

Today making the mistake of using XML is a big one. XML is no longer considered good for API coding and along with that SOAP has gone the same direction. The best way to ensure success is to use XML instead of JSON.

Error Handling Issues

In the software development world, it seems that bad news tends to spread at the rate of 100% faster than good news. If the first few people who are using your API run into errors they can’t figure out everyone else will ditch it. Poor error handling is frustrating, and so you should make every effort to ensure that it is easy to understand.

Robust error handling coupled with the use of meaningful HTTP status codes are always a good idea. Also, by linking to a Wiki, you’ll make it easier for developers to understand what’s going on.

No Security

Nowadays developers don’t want to use APIs which aren’t secure. Security is a huge concern for them, and if it does not have security measures built in, the API will not be widely accepted. Many different security measures can be incorporated like token-based CI-Server which will give access to developers to your private resources.


Now even though building a super-duper API with a tonne of features may seem to be your key to success it is in fact just one part of it. You need to make several other considerations before releasing the API. It goes without saying that once you publish an API you can’t pull back, and so every effort needs to be made to get things right from the very beginning. If the API still isn’t’ successful, you need to reevaluate how you’re marketing it to developers.