Since I started IowaComputerGurus in early 2006 I have worked on more than 100 different vendor API integrations. Now two integrations have been the same, even if they are both going to the same vendor API. Each integration project is a unique beast, the business requirements however similar are exactly that, similar. The small changes, the small tweaks that you might have from one client to another on the same platform can be catastrophic. Having done so many of these, I thought I had seen it all, from poor API's, to poor support, and everything in-between I could go on for days with the things I've experienced over the years. However, after two recent experiences, by far the most horrible I've ever experienced I thought I'd share a few lessons learned to help others out there learn from my experience over the last 4-6 months.
Goal of this Post
The goal of this post is not to flame the individual vendors that drove me to want to share. But to help educate others, to share some tip & tricks that had I learned about these before red flags might have been raised sooner and I would have had less nights working into the wee-hours of the morning cleaning up a vendors mess. Some of these items are things I've done for years, others are new, feel free to share your tips as well in the comments!
The first step in any integration is the initial sizing of the vendor. That review of their API documentation, the quick kickoff phone call where you are introduced to their team. Each vendor might handle this situation different but overall this is the initial "first glance" at what you are going to be up against. At this point in the process
- Are they going to be passing you from "team to team" within the organization? if so, be cautious promises are lost in the hand-off, implementation details are lost.
- Do they have a single location for documentation? - Check for competing documentation.
- Google the company name & API. - What do you see?
- Ask them what the support process is when you encounter an issue with the API? Do they require you to "replay" the entire transaction? Can you do it?
Right now, is the key time to look for things that don't add up. Look for discrepancies in what they say or do. In one of my problematic API projects recently we discovered that they had 4 different repositories of documentation for their API, all of them had incorrect details and following them to the T resulted in failed API calls.
One other current project the support process had an average turnaround of more than 3 business days before any "true" information was gained. This is completely horrible, try submitting a support ticket, but be sure to have someone OTHER than the primary contact that is evaluating the vendor do it. Why? Well I've worked with vendors that during pre-sales ensure your tickets get escalated as they arrive, after you sign the contract you are no longer treated the same way!
Create/Use a Quick Test Environment
I cannot stress this enough, the second that you are committed, or ideally before you commit build yourself a quick "test harness" for working with the vendors API. In almost all of my projects where I have an external integration you will find XXXTestHarness.exe as a simple C# console application. By creating this you can do the following steps quickly, but still be able to reuse your code later.
- Test to ensure you can quickly consume the API. (Is it a standard SOAP protocol with WSDL? Did it import quickly.)
- Evaluate the methods that they use for communication, do they use standard HTTP protocols?
- Try pushing junk data to the API. Do they tell you?
- Do they have matching logging? If so, are ALL calls logged including errors?
One funny/horrible story with the most recent vendor integration that I worked with involved the logging & exception routines. We followed their API documentation to the letter, submitted the requests and even received confirmed HTTP 200 response codes with success, as well as messaging noting that the data was processed with a "Success." However, we had nothing in the logs for the API call, nothing even recording the call. Come to find out their API documentation had a typo in it, and given the typo the API just ignored the posted information and that was considered a success. Since it ignored all data, it was considered a success that was not worth recording.
Once you create a test environment it is a great way to continue into creating Unit Tests or even for troubleshooting issues later in the life of the project.
Performance Monitoring & Load Testing
Another process that I incorporate into all API's both at the testing & final implementation phase is testing of the responsiveness of the API's. Logging & timing the transaction duration allows you to create parameters for performance. By knowing how long it took the API to respond if you are starting to encounter performance issues you can focus on the right area for integration early on.
However, it is important to cover this with your vendor. One vendor when we approached them to try and load test the environment to ensure that my client's end traffic load would be supported responded that "load testing against our environment is NOT allowed under any circumstances." A true sign that if you are performance conscious that you might be fighting an uphill battle!
How Invested is the Vendor in the API?
Are other people using the API? Having an API that is only used by you can be helpful in some cases. You can get what you want often. However, if you are the only, or one of very few users of an API you might not get the same level of attention as you would if the vendor had a heavily used API. In one case for a client we are the only use of an API for a vendor that has 100,000+ customers. Guess what, they don't even test their API after a new release, we have to test it and report issues back to them. Knowing a bit about their usage will allow you to be more aware of when things could go wrong.
Don't forget to ask to be added to the list of people to be notified when your vendor is going to do a code release or site maintenance. While you are at it be sure to get their update schedule as well!
Third-party integrations are by far one of my favorite things to work on. When you finally get two or more systems to speak with each other cleanly and to what they need to do it is very rewarding. However, they can be a true time-sink if you are working with a vendor that is not invested.
I have one eCommerce platform that I worked on that upon order submission 5 different vendors are called in real-time and it is a seamless process that happens in less than 2 seconds and the user has no idea. A truly elegant API solution. I have another that one single vendor API averages 13 seconds for a transaction that needs to be "real-time." I work with vendors that will jump at any report of a problem and others that will let you be down and out for days without a care in the world.
If you have your own tips and tricks feel free to share them below! Best of luck with your integrations!