Product in Practice: Transitioning Customers to a New API

Share this article

Continuous discovery is for everyone. You don’t have to be building a consumer-facing app or website to enjoy the benefits of this way of working.

But we understand there’s reluctance about adopting discovery outside of traditional business to consumer (B2C) digital products. Whether it’s hard to visualize this way of working in your context or you haven’t come across many real-life examples of how other similar teams are approaching this, we get it. The struggle is real.

That’s why we’ve started publishing this series on the role of discovery for APIs. In case you missed it, here’s what we’ve covered so far:

• We introduced APIs and how they work.
• We discussed the most common usability challenges developers face when starting with a new API.
• Teresa shared her own experience with using APIs and why it convinced her this is an area where much more discovery is needed.

Today we’re excited to share this Product in Practice story about adopting discovery habits when your product is an API.

Our discovery champion, Gary Clift, saw that the new version of his company’s API was falling short of customer expectations. Inspired by Continuous Discovery Habits, Gary was able to course correct.

By the way, we’re continuing to source more stories like Gary’s. If you’ve applied continuous discovery habits to an API and want to share your experience with us, please get in touch to let us know!

Meet Gary Clift, Our Continuous Discovery Champion

Our discovery champion is Gary Clift. He’s sharing his story based on a previous role as a Senior Director of Product, APIs.

Gary’s company offered APIs that allowed travel agencies to search and book travel content like flights, hotels, and cars.

The company had built several generations of APIs, but had not had success decommissioning older technology and moving customers to the new version. Gary’s job as the Senior Director of Product was to build the latest API and move customers to use it (instead of the old APIs), reducing the cost and risk of the older technology.

A Brief Introduction to the Technology That Underpins the Travel Industry

In order to understand Gary’s story, it’s helpful to have an overview of the technology that supports the travel industry (in this case, we’re looking specifically at airline travel) and the role of APIs.

For the past 40 years, airlines have been using a system called Electronic Data Interchange for Administration, Commerce, and Transport (EDIFACT) to share their schedules and fares. When you visit a website to book a flight, the options you see for airlines, times, routes, and classes all come from the EDIFACT system.

EDIFACT is reliable, but limited. For example, domestic fares are only updated once an hour and international fares every four hours. Global Distribution Systems (GDS)—the collection of three companies that gather this EDIFACT data and create tools for travel agencies to compare and sell flights—charge airlines for each flight segment sold, which adds up to billions of dollars annually. Understandably, airlines want to reduce these fees.

In response, airlines introduced a new standard in 2015 called New Distribution Capabilities (NDC). NDC enables travel agencies to connect directly to airline systems through APIs, bypassing the GDS. The NDC standard allows each airline to create their own API, giving travel agents and booking sites direct access to these updated features.

But NDC has challenges, too. Airlines are not always consistent in their booking process or with their rules for baggage. Plus, each airline’s system has unique error messages and codes. These inconsistencies force travel agencies to build custom software to handle each airline, which is costly and time-consuming.

At Gary’s company, they only implemented this new distribution model (NDC) on a new version of their API. Customers would need to use the new API to get the new NDC airfares. This would involve rewriting all their code, which was a significant undertaking in and of itself. But each airline applies NDC standards differently, so this led to some additional challenges, which we’ll explore in more detail throughout this article.

We mentioned earlier that the outcome for Gary’s team was to get more customers onto the new API. He has a few stories that illustrate why this was a challenge.

Story #1: Moving from SOAP to REST, Handling Workflow Variations, and Dealing with Incorrect Documentation

Adopting a new API is never easy. But that was particularly true for one of Gary’s largest customers—a global travel agency.

Their VP of Technology described Gary’s company’s API as difficult to work with and lacking adherence to what he considered best practices. He also believed that choosing Gary’s company as a vendor was negatively impacting his company’s return on investment.

As Gary spoke with the VP of Technology, here’s what he learned: The new API workflows were dramatically different from previous generations, which manifested in three major ways: needing to support a new way of sending and receiving requests, needing to support a lot of variation in the purchase process, and having to deal with incorrect documentation.

First, let’s look at what the customer had to do to support a new way of sending and receiving requests. In the prior versions of their API, developers used SOAP to send and receive requests from the server. The new API used JSON. This meant that the customer had to update all of their code to now send JSON in their requests and to expect JSON in the API responses.

The second issue related to supporting variation in the purchase process. Going back to the NDC standards, which we mentioned earlier, each airline implements the NDC standards differently. This leads to significant variations within the same NDC version.

One example is the process of selecting seats before or after you book. You may have experienced this firsthand since the process of selecting a seat through an airline's API via the New Distribution Capability (NDC) can vary depending on the airline's policies.

For example, some airlines allow passengers to choose their seats during the flight shopping phase, prior to finalizing the booking. Other airlines require that seat selection occur only after the booking is confirmed. And some airlines, like United, generally allow passengers to select seats during the booking process, but for certain fare types, such as Basic Economy, advance seat selection may not be available, and seats are assigned at check-in.

Since Gary’s company aggregated all of the airline APIs and their customers used his company’s APIs, the customer blamed them for these inconsistencies—even though they were not at fault. From the customer’s perspective, it was harder to build their own purchase flows because they needed to support all these variations.

Finally, the customer complained that the development team at Gary’s company did not do a good job of keeping the documentation up to date. They didn’t update it when features or schema changed, which caused the customer’s development teams to spend long periods of time trying to understand what they were doing wrong, as described in the documentation.

This was creating a bad customer experience for anyone using the API because it wasn’t working as intended, they had to spend time filling out support tickets, and at the end of this process, they’d learn the problem wasn’t their fault and there was no way of fixing it on their own.

The bottom line was that it took many more months to develop than anticipated. The cost to use Gary’s company’s API was higher and lowered their customer’s profits. Other competitors in the industry had similar problems but had more support from leadership to prioritize the customer developers.

This story exposes how much work is required to upgrade to a new API version. And when we don’t think through the friction it’s causing for our customers, it can be really disruptive to their business.

The solution and an important lesson: Using the interview snapshot allowed Gary to get buy-in for prioritizing and advocating for customer developers

Because Gary had recently read Continuous Discovery Habits, he approached his conversation with the VP of Technology like a story-based interview and created an interview snapshot afterwards.

Gary explains, “The interview snapshot became a powerful tool for prioritization and advocacy, helping communicate the struggles to our company’s VPs. As Teresa had noted in her book, the snapshot humanized the feedback and made the issues more relatable.”

Gary believes the interview snapshot was also more convincing to company leaders than any other tactic he’d tried: “I had spoken with the leadership team multiple times about how our APIs needed to be easier to use and the developer experience needed to be a priority. This customer interview snapshot provided concrete evidence that there was a real need.”

Summarizing his observations, Gary says, “This experience reinforced the value of capturing and communicating the customer journey. While the interview didn’t surface groundbreaking revelations, it clearly highlighted the pain points in their experience with our API. The structured storytelling format brought clarity, helping me advocate for changes and prioritize the real issues our customers faced. It was a practical application of continuous discovery—and a reminder of how much impact a well-told story can have.”

Story #2: A Frustrating Error Message Experience Put a Key Customer at Risk of Churning

In this second story, a large travel agency client wanted to move to the new API, but they were frustrated with the error responses. Gary says this was a common complaint among customers because error codes were unmanaged.

There were two primary reasons why error codes were a major pain point:

1. Each team at Gary’s company could define whatever error codes they wanted, so there were no standards.
2. Each airline also defined their own error codes, and Gary’s company simply passed these error codes on to the customer. This meant when a customer got an “error” message, they had no idea what it meant or what to do about it.

Think of it this way: When a consumer app is buggy, it creates a bad user experience. When an API is buggy, it creates failure on a programmatic level. This means that customers (usually the developers) have to spend a lot of time trying to figure out what went wrong and submitting support tickets. This is expensive and inefficient for customers (in this case, the travel agency).

The travel agency customer said if Gary’s team didn’t fix it, they would walk. This was the biggest deal in the entire company, so it was an opportunity to fix a significant pain point and save a critical customer.

The solution: A Common Error Handler Library

Gary’s team considered a few different solutions. They debated letting each team use their implementation as long as they followed the rules. (This solution was something the engineers wanted but product people hated.)

Ultimately, they decided on a decentralized library each team could use. They created a structure for all human-readable messages all teams had to follow. They organized the errors in groups, which identified which workflow step generated the error.

Gary describes the process this way: “We deduplicated errors, reduced the number from 1,300 down to 1,000, and rewrote all of them to match the new structure. Best of all, we mapped the nonsensical airline system errors into the common errors in the library. Finally, we forced governance into the process that all new errors must be sent to a weekly governance meeting, which proved critical in returning to the chaos.”

Gary personally looked at error messages from well known, best-breed APIs. Using an LLM with several prompts, he discovered a pattern.

They ultimately succeeded with the “Common Error Handler Library” and delivered it in 90 days. They practiced rolling out the new library system-wide as they had a knife-edge cutover. This involved coordinating across multiple people and teams.

Gary says this solution saved this particular customer and fixed a horrible situation for when things didn’t go as planned with errors. He also believes the introduction of governance will keep the system in check in the future.

Story #3: Missing Functionality in a New API Leads to Customer Dissatisfaction

A new customer had signed with Gary’s company, but they were frustrated by two missing features in the new API that had existed in previous versions.

The customer was expecting the new API to have several core features, including supporting Passenger Type Codes and searching flights by arrival time.

The customer assumed that Gary’s company’s system supported specific Passenger Type Codes (PTCs) essential for their operations, but the newest version of the API did not.

Previous APIs accepted free-form fields, with the core platform handling the business logic, while the new API supported only seven predefined PTCs. Gary’s company had made this change to shift some business logic from the core platform to the API in order to reduce operating costs. But the result was that the customer required four additional PTCs that were not included in the new API—and they were prepared to terminate the partnership over this issue.

The second major issue was that a promised feature—searching flights by arrival time—was delayed beyond the expected delivery date.

This feature was available in older APIs but absent in the new one. It allowed travel agencies to search for flights based on arrival time rather than departure time.

The sales team, relying on the company's roadmap, had assured the customer of its availability by a certain date. Unfortunately, the feature was neither completed nor initiated by that deadline.

For this customer, timely passenger arrivals were critical. Delays could lead to missed departures and financial liabilities for refunds. The company’s senior leadership was understandably upset and demanded a concrete timeline for the feature's implementation.

The solution and a key lesson: Working with the customer to understand their needs helps ensure APIs are designed well

Through virtual meetings directly with the customer, Gary engaged directly with the customer's Technical VP to pinpoint the exact PTCs necessary for their flight search and booking services. Gary asked explicitly what PTCs were not available and were blocking their release.

Additionally, Gary provided a revised, firm deadline for the search-by-arrival-time feature, which he personally guaranteed, committing his position to its timely completion. He delivered monthly progress reports to both the sales team and the customer so they knew the exact status of the project.

They also analyzed the required PTCs, recognizing that each code encompassed complex business rules—such as seating requirements for infants, unaccompanied minors, military discounts, or full-fare adults.

Implementing each necessitated thorough evaluation and, in many cases, new code development within Gary’s company’s services by its engineering teams. Beyond the customer’s four specified codes, they researched other APIs to identify commonly used PTCs, ultimately compiling a list of 27 new codes to enhance the new API's versatility for all clients.

Through dedicated effort, clear communication, and meticulous planning, they successfully integrated the required PTCs and the search-by-arrival-time feature. As a result, the customer launched on the new API and quickly became one of the most valuable customers on the platform.

This story illustrates that even when your product is an API, you still need to think about the customer’s experience and the usability of your product. A new version of an API is analogous to re-platforming. We have to decide what from the old API needs to be included and what can be dropped. If we aren’t working with customers to do good discovery as we make those decisions, we aren’t likely to get it right.

Key Learnings and Takeaways

After reflecting on these three stories, Gary had several key learnings and takeaways to share.

Discovery helps to reduce uncertainty.

“When it comes to the discovery and delivery of APIs and software development kits (SDKs), one key motivation stands out: reducing uncertainty,” says Gary.

To use an API product, customers need to spend development resources to implement it. They then need to depend on it to run their businesses. They don’t want it to change all the time.

Reliability is one of the most important factors. Gary believes reducing uncertainty is the key to solving real problems that customers are willing to pay for.

“The opportunity solution tree is an excellent framework that helps reduce uncertainty by guiding teams to identify customer opportunities, generate multiple solutions, and test assumptions,” says Gary. “This process ensures that opportunities are rooted in actual customer needs, eliminating the guesswork of the value of the solution.”

Gary also calls out the value of exploring multiple solutions as a way to reduce the risk of committing to the wrong path and increasing the likelihood of discovering the best possible solution. He believes that testing assumptions allows you to expose hidden risks early in the process.

Summing it all up, he says, “The opportunity solution tree framework embodies the principle of reducing uncertainty at every stage, aligning with one of the primary human motivations while driving business success.”

Get creative when it comes to finding developer customers to speak with.

Gary recommends using your Developer Relations (DevRel) program as a source to get developer interviews. If you have a newsletter, tech talk, town hall, or conference, Gary suggests using these as places to sign up developers for interviews.

If you find yourself in a situation where your customer will not let their developers be “distracted” by a vendor in an interview, asking your customer’s development team to do friction logging can help find areas where the API or SDK needs improvement in interface usability, incomplete features, or missing features.

Commit to the practice of assumption testing.

Gary cautions to remove your ego from the process and believes assumption testing can help you to achieve this. “Assumption testing helps eliminate confirmation bias, the Dunning-Kruger effect, and other cognitive biases. The definition of success for product discovery should be to find THE best solution that addresses an opportunity, not to find YOUR best solution.”

Don’t forget to share your work.

After you have conducted an interview, make sure you share your findings with your peers and leadership. “Real customer words have a profound impact—bad or good—on your team,” says Gary. “But remember that interviews are customer opinions often rooted in frustration, so quantitative messaging is also important.”

Do you work on an API team that needs help getting started with discovery? Check out our comprehensive guides on what discovery is, on how to conduct effective interviews, and how to run high-quality assumption tests.