The developer’s guide to choosing the least shitty APIs

Depending who you talk to, APIs are either a developer’s secret weapon that adds a ton of value, or they’re a flawed technology and a major liability to your infrastructure. The funny thing is that both are true.
 
APIs are extremely popular for both enterprise and individual developers. So much so, an entire new industry of API management software companies has emerged to help businesses make sense of the thousands of API options.
 
At the same time, developers have a love-hate relationship with APIs for the simple fact that many have proven to be unreliable. When an API fails to live up to its promise, developers are left with expensive rework, or worse — a complete rebuild.

Why There is Instability in the API Space.

It’s important to note that not all APIs have instability issues. There are over 10,000 open APIs, and that doesn’t include the proprietary ones from the Googles and Amazons of the world. With so many available, it’s not surprising that many are poorly built while others simply vanish into thin air without warning.

So why are so many APIs unreliable?
 
Kin Lane, in his API Evangelist blog, presents an insightful hypothesis. He believes the general instability of the API space has to do with the changing business and investments priorities that fund APIs. He states:

The reality of the startup game is that us API consumers aren’t actually the customer, we are just numbers in a larger game where startup founders and their investors are looking for enterprise customers to purchase their startup getting the desired exit. The API is just about attracting consumers, who will do the legwork to bring in users, adding to the value of a company.

While Kin’s observation rings true for certain APIs that make a big splash and then suddenly disappear, there are definitely other factors that affect the quality of an API — starting with the API provider. Three realities of API dev that contribute to a lack of quality include:

1. APIs are built too fast. Technology is moving at the speed of light and deadlines are tight. The good news is that frameworks like Flask combined with Zeit can help you get your API running in less than an hour. But when developers rush, they often ignore a rule or skip a documentation update. Those shortcuts eventually cause problems.
2. APIs lack adequate authorization. Without the right authorization and authentication protocols, your API may cause a security breach through the exposure of compromised credentials, session capture, or replay attacks. At the very least, APIs should use authentication standards like OAuth and consider using API Keys instead of credentials.
3. APIs aren’t tested properly. It’s very common for an API developer to do a quick manual test before deploying it and relying on feedback to iterate. This old-school approach isn’t optimal when you consider the cost of rework for the hundreds of developers that might be implementing your API.

Building a high-quality, secure and well-documented API requires discipline and enough time to get it right. If you think of your API as a product and the developers as your customers, you’ll create an API that will function properly and provide a great user experience.

The Hazards of Building on an Unstable API

Unstable APIs cause a lot of pain, frustration and financial strain. In addition to longer development cycles, unplanned rework, and a higher defect rate, building your service on top of a third party API can be a huge risk if the API changes without warning.
 
When an API fails, anything that was built on top of it must be fixed, not just the API. Depending on the complexity of the implementation, a rework can cost the company time, money as well as hurt their reputation. If a company fails to meet their customers’ expectations or there is a security breach because of an unstable API, the damage is unquantifiable.

Beyond major setbacks, low-quality APIs can simply make a developer’s life really hard. When an API doesn’t adhere to best practices or is poorly designed, developers will eventually give up on it and look for a better solution.
 
Some of the annoying issues of bad APIs include:

• Poor user interface. While an API interface doesn’t need to be pretty, it still needs to be functional and easy to use.
• Vague error codes. Most APIs experience errors — but when an error message does not help developers find and fix the issue quickly, it causes stress and a lot of wasted time.
• Not Really RESTful. The documentation states that the API is RESTful, but you quickly realize that it’s a lie or they don’t know what they are talking about.

These are just a few of the bad experiences that developers have faced when dealing with APIs that were not up to snuff. When a developer gets burned a few times by these lame APIs, they start to group all APIs together as a liability.

Telltale Signs You’ve Found the right API

Evaluate APIs in the same way you would research other tools and technologies for your project. Developer communities are the best place to start. Quality APIs are usually easy to spot via the discussion groups and forums.
 
Beyond your peer network, knowing about the company and people behind the API will give you some confidence that the API will not suddenly vanish from lack of funding. When you are evaluating the provider, the most telling signs that they are legit is through their communications, documentation, and the resources available to test and troubleshoot issues.

Communication

Providers who have their act together will openly communicate about updates, problems, or news about the API. The more information developers receive, the more confident they become in the APIs quality and performance.
 
GitHub is the best place to do a quick check on the most recent updates of an API. You don’t want to start building your entire product around an API only to learn later that the last update was in 2014.

In the above example, Basecamp actually uses GitHub Wiki to house their documentation, making it easy for developers to find all the recent communication they need to make an informed decision about how and if the API is right for them.

Documentation

There is no such thing as self-explanatory code. Even if you think it is the most intuitive tool ever built, it’s likely someone will have a question. A well-designed API will always have support docs to thoroughly explain its functionality and use cases.
 
When documentation is clear, comprehensive and easy-to-use, it is a sign that the API was designed with the developers in mind. Documentation shouldn’t merely explain functionality, but it should also help developers understand why and how the API will help them make their project a success.
 
For example, Airtable substitutes user-created values for the developer’s own language to help them understand what the API will actually do for them. By customizing generic fields with custom examples, it makes it really easy to gain the confidence of the developer and get them started on the right foot.

Know your audience. When you put yourself in the shoes of your customers (developers), writing documentation becomes a clearer task. Imagine what you would want and need to succeed, and start documenting.

Functionality

If an API doesn’t provide a sandbox mode to test and play around, it’s difficult for a developer to take a leap of faith that the API will perform. This is especially critical when you are dealing with data. Developers want to test the production environment with dummy data before implementing their company’s assets.
 
Stripe’s API is a great example of providing several testing options to ensure the API is the right fit for your requirements. Stripe allows you to connect to test accounts, where you can use your terminal window and start testing right away.

By testing an API, developers can see the value quickly, but also save time and frustration by ensuring the functionality is right before doing a lot of work.

Troubleshooting

When an API behaves unexpectedly, it should be easy for developers to understand what is happening. High-quality APIs enable developers to inspect all the calls, their inputs and responses to identify issues behind the scenes.

All APIs are not created equal. When you find an API that suits your needs perfectly, don’t jump on board just to check it off your list. Do some due diligence to make sure that the provider communicates, documents and provides support. It will save you time, money and your sanity in the long run.

The Productization of APIs Will Boost Quality

APIs have customers. They are the developers that use them every day to improve their own services. APIs should no longer be treated as a quick hack to provide functionality, but rather a product that delivers value.
 
Like any product, success is measured by the quality of functionality and level of customer support that delivers a positive customer experience. If every API provider took this approach, there would be a lot less shitty APIs in the world.

IPinfo is a comprehensive IP data and API provider with flexible pricing plans to meet your business needs. We handle billions of API requests per month, serving data like IP geolocation, ASN, VPN detection, and more. Sign up for a free account or contact our data experts to learn more.