Making the Most of Your API: Lessons Learned When You (and a Partner) Aren’t Speaking the Same Language

Dominic Lachowicz |

July 30, 2013

Making the Most of Your API: Lessons Learned

Over the past couple of weeks, a few members of our development team have been working part-time to upgrade one of our applications to the latest version of a partner’s SOAP-based API. This partner recently announced that they were (rather abruptly) discontinuing support for the previous version of their API. One of their goals was to maintain API compatibility, so in theory, all that was supposed to be required of us to complete this upgrade was to:

  1. Upgrade our operating system (OS) to Windows Server 2008.
  2. Import a few new digital certificates into our certificate chain. Our partner was enhancing their system to use a stronger security mechanism.
  3. Point our application at a different URI that supposedly supported the same set of SOAP messages.

In theory, this should have been a quick migration that could have been handled by our IT department and should’ve fallen under the “routine maintenance” category. No code changes should have been necessary, merely some adjustments to our system’s configuration and a round of regression testing. Unfortunately, it was nothing of the sort, in large part because the API contracts were broken rather significantly. The responses we received from the partner’s service were uncanny. Some responses complained about the WS-Security headers. Others complained about invalid content in the SOAP body, which would be odd if they’d preserved API compatibility. We knew that we could get to the bottom of this quickly if only we had access to developer-level documentation, or if we could see some examples of valid requests and responses. If we had that, we could compare and contrast that data against what we were generating. In the proceeding weeks, we exchanged no fewer than 40 emails with our partner and had no fewer than six (6) phone calls and GoToMeetings. While our partner was being extremely responsive, we were not making forward progress. And before you knew it, the “quick upgrade“ had turned into an unplanned – and expensive - ‘nightmare’ project.

As the VP, Engineering for an organization with a public API, I strongly believe that providing your developers with a top-notch onboarding process is just your ticket to the game. In today’s environment where APIs are a clearly a competitive advantage, those that don’t offer a compelling developer experience will be replaced with ones that do. Many companies these days are choosing to work with API Management Providers, such as Mashery and Layer 7, to provide a more fulfilling and comprehensive developer experience. These providers provide top-notch environments to make your developers’ experience as seamless as possible. Their services include services such as in-browser API testing, developer documentation, and community-based forums where developers can share their wisdom and experiences. One of the more compelling examples of this is Mashery’s IODocs feature, which allows 3rd party developers to experiment with your APIs real-time in their browsers, and dissect everything – from how URIs are constructed, to the JSON and XML request and response packets.

In our case, we didn’t have those resources at our disposal. But, fortunately, not all hope was lost. Our breakthrough moment came when we had the idea to ask our question a little bit differently. Rather than finger pointing or sending yet another email, we asked our partner a very simple question: Can you help us make this single SoapUI test case work? If we could get that one test case working, we were confident that we could translate that into working code in short order, or else at least shed some light on the problems we were experiencing. We took a gamble that our partner would have someone on their team that had experience with SoapUI. It was a long shot but it worked out. Once our partner helped us get the SoapUI test working, we were able to turn around the code in a couple of days.

While there are several morals to this story, for me, one of the more compelling tales was SoapUI’s usefulness. Sure, SoapUI is a fantastic web services testing tool. More importantly than that, it’s a tool with broad industry adoption, and that’s why it was helpful in this case. Up until this point, we (and our partner) literally weren’t speaking the same language. By externalizing our problem onto a ubiquitous tool, we were able to get on the same page and move forward.