How to Prepare for a Custom API Integration Project

The concept of the API, or “application programming interface”, has revolutionized the world of software development on a global scale. In the past, developers used to extend software by either building on top of their platforms or installing extensions and plugins to handle additional functionality. Today, you can build custom software that seamlessly interfaces with third-party applications all because of the advent of data-sharing and the API.

Why do this? Well, you get the best of both worlds. In some cases, you can build internal workflows that can heavily influence your bottom-line while utilizing third-party tools that perform their tasks well. Or, you can build portals at the center of many tools being utilized to enable easier management. Whatever the application, custom API integration projects are on the rise as more and more services make their data available to the outside world and more organizations utilize services to handle their ongoing software needs.

While API connectivity can make almost all software extensible and highly customizable, there are things that companies seeking to undertake a custom API integration project must look out for. Like anything else that you build, making some initial missteps can result in major issues down the line. During introductory calls with clients interested in building out custom API integrations, I typically highlight some of these risks and some strategies to better prepare for the project. As with any development project, preparation and due diligence go a long way to avoid future frustrations. The purpose of this post is to draw attention at a top-level to things you should focus on during planning and development to prevent any issues from appearing later on in the project.

First: Documentation

Documentation of any API is key. The first thing you should do when embarking on an API integration project is to request any and all documentation that an API’s provider offers. Documentation helps in a few ways. First, it lets you get a sense into the clarity of the data source, and how well implemented it is. Shoddy documentation never makes for an easy integration. Documentation that is poorly produced will give you insight into whether the provider takes data sharing seriously or is just offering an API to check another box on its product offering spec sheet.

What do you want to look for in the documentation? We’ll dig into a few items below such as functionality specific to your needs. But in your first glance, look over the API architecture. How will the system send payload back to you? Is this a truly RESTful API or is it some other concoction? What does the system support in terms of authentication? And, what levels of security are in place for the data transfer?

Finally, look for obvious signs of overall quality or consistency. What was the last revision date of the documentation? If it was more than a couple of months ago, then the system may not be regularly updated. That is a potential red flag. Also, did you get this documentation in a PDF file or some other fancy delivery method? Like anything else that you deal with, presentation matters. The worse the documentation, the more you are in for turbulence during your integration and development phase, so be on the lookout for inconsistencies and any other issues that may make your life difficult later.

If in Doubt, Get a Human Contact

I have a general rule for all API integrations… The fewer users an API has, the more likely you will need to have someone to reach out to for help. When you look at the most popular APIs available today, systems we integrate into often, you can see that the documentation is thorough and it isn’t always easy to get in touch with a human. But, that is usually because their systems have been tested out by thousands of users. Take Stripe as an example – their system was designed around the API being the core offering. Their documentation is thorough and the system works flawlessly. I’m unsure we’ve ever contacted support at Stripe, and we’ve integrated into their system hundreds of times.

On the other end of that spectrum are your smaller organizations that are building out APIs specific to customer demands or requirements. When you have only a handful of API users, you are much more likely to need a human being to work with to assist you in understanding how it all works. You can sense this will be an issue in the previous step – when reviewing documentation. Lesser-used APIs are always going to be more of a hassle to deal with, and you need to prepare in advance to work through these roadblocks by ensuring you have some level of communication with the provider.

Luckily, in our experience, if you are integrating to a provider with a small or limited data feed, they do take you seriously in that at some level you or your customer is paying for the access. With that in mind, they tend to work together with developers to ensure the API is working reliably and providing the necessary data to fulfill the customer requirements.

Check License and Usage Terms

This is an area where you can really be taken by surprise later if you are not careful. We see this more with larger companies than we do with smaller organizations. APIs do cost money to run, and especially when offered in conjunction with free services, don’t be expected to eventually run into a usage tier where you will be expected to either pay for services or have your connectivity limited via access-based usage ceilings.

Many companies offer up APIs for a fairly generous amount of usage, only to eventually turn off access, throttle or otherwise limit usage unless license fees are paid. Most API systems authenticate users via custom keys or access credentials, allowing them to track usage. When usage goes above a certain level, they will look to collect license fees or block connectivity. The worst is when the provider doesn’t tell you – your app will just stop working!

Recently, many users of the Google Maps API were taken by surprise when their integrations stopped working. Google Maps started to require a nominal fee to enable their embedded maps and API calls for integrations. Sure, Google warned folks first. But you know, who checks their email?

Figure out up front what your costs will be and come up with a strategy for either mitigating those fees or at least understanding what your costs will be as your application scales. We’ve seen this with many premium data feeds – for example, if you are building a financial application that derives its value from stock values, you’ll need a data feed to get that information. The providers of that data are typically going to charge you for each request. You can either plan to pay for those requests or start some level of localized caching to minimize requests. Either way, you need to plan ahead.

Don’t be taken by surprise – analyze and in some cases check for competitive data sources. You’ll once again avoid stress later on down the line.

Architecture Matters!

One thing you should focus on prior to subscribing to a data feed or committing to an integration via development is how your application will utilize the API to achieve its desired functionality. Ideally, an initial discovery process will help your developers identify which particular calls to API endpoints will be necessary, based on how your application works and how the third party offers data. You need to have a sense of how you’ll make your project specification’s requirements work within the confines of the particular API you have to connect to.

I love custom development because it affords us the opportunity to say “yes” more than we say “no”. However, API integration is one area where our efforts can be handcuffed by the abilities of the system we are going to be connecting to. As such, it’s important to have a project properly architected in advance, so that the capabilities of the API can be vetted.

To be safe, you or your developer should not only identify what endpoints exist but also how they work. What data needs to be sent? And, what data will be returned? Will the methodology behind which the API is built enable you to perform the tasks you need to in order to achieve success?

Also, you should at this point consider what happens where. If an API offers some data handling on their end, does it make sense for you to do the same? Does the API offer a way to perform a task that you believe you can better perform yourself? No matter what the particular instance is that you are architecting, make sure you take the time to plan before pulling the trigger on your project. Whenever a project is dependent on a third party you must do all you can to minimize any risk that you will be stuck in a corner later.

Remember Error Handling!

So many lower-level developers integrate APIs in ways that make the third party connectivity a lynchpin in their own application. In any integration, you are tying into an API to perform a task you can’t do locally. So it’s impossible to prevent outages when an API is not performing properly. However, proper error handling can prevent your application from dying when an API does. 

The key to proper error handling is twofold. First, you have to know what the best practices are in terms of handling errors as they arise. This is an entirely different topic that we can review in a thorough blog post in the future! The second key is that you need to be able to predict where those issues could arise in advance of them happening. This is an area where only experience can answer the question. 

Post-Development Bonus: Stay Up To Date

I believe the above points are all equally important when planning and preparing for an integration project. However, what about when your project is over and deployed? Well, the most important thing you can do then is to stay up to date on the APIs continuing improvements. As I said, these systems are known to change. Luckily, most providers will give you advance notice about any changes to either the business terms or the functionality. As in my Google Maps example above, however, many people simply don’t read their emails. So, be sure that you stay current with any updates that come along from providers that are integral to your software. Most of the time, these types of issues are avoidable, but you’d still be surprised how often people overlook the simplest of tasks such as staying informed.

Wrapping Up

I think that projects involving custom API integrations are the most interesting and oftentimes most fun for our development team. Typically, when we integrate multiple systems together there is a benefit for the client that is immediate and calculable. A finely orchestrated series of API integrations is one area where most businesses could see a tangible benefit quickly, which is ultimately a fulfilling project for a development agency. Hopefully, by considering the above points, your integration project can serve as a valuable investment for your company as well.