api documentation - Elliot's portfolio

Portfolio

Expedia Group
Helping partners integrate
Expedia's APIs from the
ground floor
A brand new approach to gaining new connectivity partners for our API products through intuitive technical documents that made integration as simple as possible, while convincing decision makers to dedicate resources to the effort.
A 0-1 effort that changed how we talk to our connectivity partners. From pure technical expertise to helpful guide with their best interests in mind.
The problem

Expedia was only offering connectivity providers access to roughly 40% of their capabilities, which was far behind competitors.
We were missing a technical document that was as equally an implementation guide as it was a marketing pitch, written to simultaneously persuade and empower.
A connectivity gap
Most hotel partners don't list exclusively on Expedia. Instead, they use connectivity software, which are independent platforms that distribute rate and inventory changes across every channel simultaneously.
For example, when a hotel updates its rates for a holiday weekend through their connectivity provider, that one change should propagate to Expedia, Booking.com, Airbnb, and every other channel automatically.
This is what connectivity should look like.
A gap that became a chasm
But for that to work, each travel company has to give connectivity providers access to its APIs. And Expedia was only offering access to roughly 40% of its capabilities, while competitors were providing full or nearly full access.
The result was that most partners had to make changes twice and Expedia ran the risk of showing incorrect rates and outdated content. Some partners got so frustrated that they stopped listing on Expedia altogether due to the hastle and inconsistency.
This is how it actually looked.
The goal

Make it as easy as possible for connectivity providers to build the missing integrations. That meant creating a technical document that could serve two audiences at once: the decision-makers who needed to be persuaded it was worth building, and the engineers and product managers who needed to know exactly how to build it.
Two goals, one document
Connectivity providers had to choose to prioritise building Expedia's integrations over everything else on their roadmap. And once they decided to build, they needed clear enough guidance to actually succeed.
The document had to solve both problems simultaneously.
We became familiar with our users
Discovery process included becoming familiar with who would actually read this document, what they look for in API integrations, and what would make their lives easier.
We found that they needed to quickly understand whether the engingeering investment was worth the trouble, if engineering had enough technical specifications and context, and general UX guidance for those teams who did not have a dedicated UX resource.
...and our competitors
Booking.com, Agoda, Priceline, and several non-travel companies were publishing similar documents.We looked at what resonated, what fell flat, what felt informative, and what seemed superfluous.
One key finding was that the best documents sold the value proposition before getting into the specs, but that value proposition still assumed technical knowledge and used internal jargon that could lose the reader. They also assumed advanced UX knowledge without knowing if they had the requisite resources.
This was the validation that we needed that we were heading in the right direction.
The solution

Create a task-oriented document that was based around answering the "why." Aim for simplicity. Assume little-to-no UX knowledge from the reader while also clearly articulating the basics of creating a great product for their - and Expedia's partners.
A document that persuades, instructs, and guides
So we knew we had to answer two separate questions.
Why should you build this? How do you build this?
Our "opening pitch" targeted the decision-makers first, the ones who approve the roadmap item. I led with explaining how integrating this API would help them attract and retain hotels and how to approach this document.
Then I gave a high-level explanation of how each API component functions. I wanted to be up front about what they were being asked to build from a zoomed-out perspective.
The engineer or designer tasked with building this could also use this as a quick reference for the component's basic behaviors.
Then I dove into each individual use case. In this example, it was our UI recommendation for how a property would search for a reservation.
As the connectivity team started building the individual parts of the component, this would guide them through the basic functionality of that specific component.
Since we didn't know if they had a dedicated UX team, we provided visual examples of how each flow operates. These example flows came from Expedia's own property management software.
This is another sample: initiating a guest satisfaction refund. It's a slightly more complex flow, but broken down into individual steps so the user would be able to break down multiple steps into easy-to-follow individual parts.
I then provided additional guidance for the teams without UX design resources, defining basic design principles. This would help them not only build this specific component, but would hopefully act as a reference for all future UX asks.
We provided examples of these best UX practices from the component itself, so while the guidance was general, it was also directly relevant to the capability they are building at the moment.
For a quick reference, I attached a UX checklist and a terms glossary. We designed for the UX novice and assumed they would need all the guidance we could give them. I figured that a short, descriptive resource would help keep them on point so they could build the best experience possible, no matter if they didn't know the difference between pixel and a paddle.
The impact

The new UI guidelines met our users where they were, no matter if they were seasoned design professionals or had never heard of Figma. Providing simple, visual, and friendly guidance proved to be a boon for our API expansion, a benefit for Expedia, the connectivity partner, and all the hotels they serve.
87.7%
API adoption success rate
The document directly drove an API adoption rate of 87.7%, giving us a clear signal that the persuasion and implementation structure were as effective as designed.
100%
Approval rate from providers
In a post-launch survey, every connectivity provider strongly agreed that it was integral to successful implementation. This validated the decision to invest in quality documentation rather than just having faith that the providers will figure it out.
100%
Demand from providers
Providers reported greater confidence in their understanding and use of UI principles, especially among those teams without design resources. 100% stated that they wanted similar documentation for all future integrations.
Why it matters
This project showed that technical documentation is content design. The structural decisions of leading with value, grounding specs in proven examples, and writing UX guidance for non-designers, were the same as any product content work. The medium was different but the discipline was the same.
What I learned
Holding two audiences in mind simultaneously ended up being my biggest challenge. These are conflicting audiences who find value in different approaches. Layering the business case into the technical overview rather than separating them was the hardest thing to get right, but ended up being the very thing that made the document work.
I also learned that "document" can be a highly impactful deliverable in content design. Sometimes the most vital content work happens before anyone opens the product. A well-written technical document that makes the right people want to build is upstream of everything that comes after it.
The 100% feedback asking for this format on future integrations was the best possible signal: not just that the document was good, but that it changed the standard for what documentation could be and was ultimately what providers needed.
Let's work together
Chicago, IL
emcrumpley@gmail.com
Name

Email

Message

Comment

Expedia Group

Helping partners integrate

Expedia's APIs from the

ground floor

A brand new approach to gaining new connectivity partners for our API products through intuitive technical documents that made integration as simple as possible, while convincing decision makers to dedicate resources to the effort.

A 0-1 effort that changed how we talk to our connectivity partners. From pure technical expertise to helpful guide with their best interests in mind.

The problem

Expedia was only offering connectivity providers access to roughly 40% of their capabilities, which was far behind competitors.

We were missing a technical document that was as equally an implementation guide as it was a marketing pitch, written to simultaneously persuade and empower.

A connectivity gap

A gap that became a chasm

The goal

Two goals, one document

We became familiar with our users

...and our competitors

The solution

Create a task-oriented document that was based around answering the "why." Aim for simplicity. Assume little-to-no UX knowledge from the reader while also clearly articulating the basics of creating a great product for their - and Expedia's partners.

A document that persuades, instructs, and guides

The impact

87.7%

100%

100%

Why it matters

What I learned

I also learned that "document" can be a highly impactful deliverable in content design. Sometimes the most vital content work happens before anyone opens the product. A well-written technical document that makes the right people want to build is upstream of everything that comes after it.

The 100% feedback asking for this format on future integrations was the best possible signal: not just that the document was good, but that it changed the standard for what documentation could be and was ultimately what providers needed.

Let's work together