Every site we build begins with the NewfangledCMS. This sophisticated core of code is customized to meet each client’s specific needs, and it handles the vast majority of each website’s functions, especially those related to creating, editing, and publishing content, as well as tracking overall site traffic and specific users’ on-site activities.
However, most every site we build also includes at least one or two integrations with other software products or services that complement or augment the functionality found in the CMS. The most common of these (for our clients, anyway) are marketing automation and CRM integrations with products like Act-On and Salesforce. Because they are so familiar, these super-common integrations are handled easily as a standard part of the development process.
But the more complex the site, the more likely we are to integrate with other, less familiar systems that handle everything from e-commerce to data processing (as we’ve done with Merge Records to handle their digital media assets). Either way, we connect the CMS with these third-party systems using Application Programming Interfaces, also called APIs.
What is an API?
An API is a set of rules that dictates how information is going to be exchanged between computer systems. APIs make it possible for different computer systems to exchange information in a meaningful way. Think of it as the secret handshake that gets your computer system access to another system’s goods, allowing you to link up with that system in a variety of predefined ways. APIs come in all shapes and sizes and handle everything from processing credit cards, to getting shipping rates, to even how many people “liked” your website on Facebook. There are no limits to what type of information is exchanged and how that information is sent back and forth. Every API is unique and will therefore come with it’s own set of challenges. Asking the right questions and having the right information upfront can make the integration process smoother and faster.
What Do you Want to Do?
The first question for any API integration should be what you are hoping to accomplish and which system you’ll be connecting with to achieve that goal. As simple as this question sounds, it really needs to be answered fully before any development work begins. The last thing you want is to have a developer spend the time and effort integrating a system only to finish and realize it’s not capable of doing what you’d hoped it would. That’s why it’s important to do your research upfront and understand exactly what you’re trying to achieve by doing the integration. Taking the time to understand the limitations and capabilities of an API means you’ll be less likely to run into major pitfalls during the integration.
That brings us to the second part of our question; who is the API with? To a developer, this question can give us a great deal of information and insight into the difficulty of an integration. If the API provider is a large, well known company like Facebook, PayPal, or Twitter, we know that the API integration has been done countless times before by countless numbers of people. Large companies like the ones listed above spend a great deal of time and money making sure their APIs are well documented, accurate, and function correctly. This makes it much easier for a developer because we know that if we run into any issues during integration, we can easily find resources online to help correct the problem. On the other hand, if the API provider is a smaller company, or if it’s a new API that hasn’t been thoroughly tested, it’s going to be much more difficult for the developer to find help when they run into issues. This in turn will result in more development time as the programmer has to spend more time troubleshooting what could be a relatively simple and easy fix.
What Documents Do You Have?
Another challenge for clients is gathering the right technical documents to give to their developer. More often than not, clients aren’t sure whether the documents they have (if any) are what the programmer is looking for. So what exactly is a programmer looking for when they ask for these documents? In short, they’re looking for step by step instructions explaining how to build the API. It’s similar to building a lego set. There are descriptions on the box explaining what’s inside, but when you open the box, you get an instruction booklet that explains how exactly to put it all together. That’s what programmers are looking for: they want the instruction book.
However, just having the instruction book isn’t always enough. The fact is that not all technical documents are created equal, and poorly documented API’s can add a great deal of time to an integration. As a result, there are a few things that you should look for in any technical document. Really good documentation will have plenty of examples in it. It’ll give the responses they are expecting as well as the responses they will send in return. It should also have an appendix that outlines all the different features of the API. In general, the more information available to the programmer, the easier it will be for her to do the integration. Considering the amount of time poor documentation can add to an integration, it’s fair to say that you should take documentation into account when choosing your API. If it comes down to choosing between similar API’s, choose the one with better documentation.
Who is Our Contact?
A commonly overlooked aspect of API integrations is having a reliable contact. Remember that an API is an exchange of information, which means there are two sides to every API. If one side of the integration is having difficulties it’s important to have a contact on the other side to reach out to. This is especially true for APIs that have less documentation or are relatively new. If a developer runs into an issue during the integration, it can often be difficult to determine which side of the API the error is coming from. That’s why having a reliable technical contact on both ends is important and can ultimately speed up development time. The last thing you want is to have the client play middle man. This will only add to the time it takes to get a response and will often cause information to be lost or mistranslated.
Do We Have Access?
The final piece to any integration is having access to the other system. By this I mean access to the client’s account within the third-party system, not access on the back-end, via the API. If you’re trying to send information to a different computer system, it only makes sense that you’d have access to that system’s front end so you you can confirm that the information made it there correctly.This typically means providing the developer with your login credentials to the third-party system. Having immediate access will let the programmer know if there are any issues and address them then and there. Having to wait a day or more to see if your tests went through can cause a project to easily miss its deadline if you run into any problems.
The lesson to learn is the more information you have upfront, the smoother the integration is going to go. Having reliable contacts, easy access, and plentiful documentation will make any integration run as smoothly as possible.