What is an API?
The information outlined in this article has been designed to help you avoid some common pitfalls and make sure your API integration project stays on track. But first, let’s talk about what an API actually is.
Put simply, an Application Programming Interface (API) is a secure set of tools that allows different systems to share information over a network, typically the internet. An API is usually created and hosted by a single company, and developers at other companies then write code – hosted elsewhere – that connects to the API and communicates with it.
Using APIs, different applications can all make use of shared data resources, whether that means connecting a single company’s website to its mobile application, allowing distributed businesses to share inventory information, allowing trusted third parties to access and utilize data in an open-source plug-in, etc.
What API projects look like?
Let’s say that a large distributor of bicycles has a huge warehouse filled with bikes and accessories that they ship out to independent retailers around the country. They want to create a private website through which their retailers can replenish inventory in their stores. This website needs to display current information about product prices and availability to the retailers. And this price and availability data resides in the distributor’s back-end inventory management system.
Luckily, the company that created the inventory management system has an API through which data can be sent and received. Therefore, when the distribution company builds this retailer website, their developer connects the website to the inventory management system using its APIs. In this way, the website can provide the retailers with access to price and quantity information, and it also updates the distributor’s inventory system when orders are received from those retailers.
Why do so many integration projects fail?
Unfortunately, the very nature of API integration projects causes them to be more likely to fail because they often require close coordination between two different parties: 1) The party that created the API documentation and 2) the company that needs to connect to that API. It’s easy for each party to place blame on the other party, making the whole project devolve into an acrimonious war with two development teams hurling accusations at each other.
This typically results from the following problems.
1. Unknown bugs
APIs are powered by software, and bugs are a fact of life in software development. The problem with many APIs – especially those from small- or medium-sized companies that are accessed by a small number of applications – is that they often contain bugs that are not yet known before the project gets underway.
This means that bugs often crop up unexpectedly during the course of an integration project. Even worse, bugs are frequently discovered only during the final QA phase of many integration projects, causing frustrating delays late in the game.
2. Poor API documentation
It takes a lot of work and specialized expertise for a company to build an API from scratch. It takes even more work (and dedication) to create the type of clearly-written documentation that developers need in order to integrate with that API, and to keep it fully updated at all times.
This is often so difficult that even many large companies fail to sufficiently document their APIs. (For example, for many years Facebook was notorious among developers for having a very poorly documented API.)
3. Differing expectations
Often times, the two parties are not on board about the necessary functionality of specific parts of an API (known as “endpoints”).
When designing an API, the individual(s) who are defining the data sets, access protocols, and security rules of the API have some idea about which data sets other parties and services will need, and how those data sets will be used. Sometimes the person designing the API will limit the endpoints to allow access only to a subset of data, or only allow that data to be manipulated in certain ways (e.g. perhaps the data can be downloaded and manipulated by another service, but cannot be uploaded back into the original database).
If the parties or services using this API are unable to access data they need, or to use that data in the desired manner, this can create delays. This is because endpoints might need to be created or modified, or the software being integrated might need to be changed in order to work around the API’s limitations.
4. Missing functionality
APIs can be thought of as products – and like most products, many companies who have created APIs are interested in upgrading and enhancing them to meet their clients’ needs. It’s common for an API to be missing some critical functionality that a customer requires for their application. However, adding new API functionality can require a significant investment that the company did not expect or budget for. This often results in unexpected delays and failure.
5. Communication and scheduling conflict
If any or all of the above issues occur, the easiest way to resolve them is by having software developers on both sides work together to make sure that all requirements are being met. This may be a relatively simple matter if all involved parties work in the same physical location for the same company, but more often than not, the developers involved will have other demands on their time, work on different schedules, live in different time zones, etc., etc.
In addition, even developers who are accustomed to working on different types of code (e.g. UI/UX developers versus backend/database developers) might have subtly different language for referring to similar code elements. Any of these sources of communication or schedule conflict can propagate through the development process, creating expensive and frustrating delays.
So what you can you do to maximize your company’s chances of success when looking for API help? The most important step you can take is partnering with a development firm that has a broad range of experience with API integration. That way your project will start off on solid footing and the issues you encounter won’t become roadblocks.
In our next blog post, we will outline several strategies to put in place at the beginning of any API project in order to reduce risks. Stay tuned!
