Customer Experience APIs: The missing layer

APIs are becoming more ubiquitous as time goes on. BFFs (Backend For Frontend) are common language, DDD is gaining more traction and API design principles are everywhere. Despite all this, we continue to see organizations following all of these practices struggle to adopt new channels.

And we’ve noticed a pattern around complexity that’s lurking in our channel BFFs. This complexity cripples our speed to market with every new channel we add or every change in our customer experience.

Let’s start with an example. Imagine building a platform like UberEats. One key feature of this platform is “browsing” restaurant menus for food delivery or pick-up. From an architectural lens, this feature often looks like this picture where orchestration is scattered across different BFFs.

“Browse” orchestration logic scattered across BFFs.

Here, the Mobile BFF orchestrates calls to Restaurant, Menu, and Offer APIs to surface the “Browse” experience¹. Other channels, existing or new, also need the same orchestration logic. So we end up with, more or less, the same logic duplicated in each BFF.

This eventually creates a tangled mess of complexity across channels. Time and again, we’ve seen this challenge at different organizations. The sole focus on channels and business capabilities led to an architecture that either:

• Missed conceptualizing the Customer Experience as a bounded context or
• Hid the Customer Experience (inadvertently) behind other service boundaries.

In either case, the result was the same. The experience was difficult to share and reuse across channels.

In this article, we introduce:

• Codifying customer experiences into the architecture as APIs — Experience APIs.
• How Experience APIs become shareable and reusable to enable Evolutionary Architecture.
• The benefits and implications of using Experience APIs as a design pattern.

What is an Experience API?

A service boundary around customer journeys as an extension to business capabilities. With this approach, we model customer workflows into reusable, channel-agnostic APIs.

Experience APIs as an Architectural Layer

Let’s understand the difference between Domain APIs, Experience APIs and Channel BFFs.

• Domain APIs: how the business works (aka business capability).
• Experience APIs: how the customer interacts with the business (aka customer journey).
• Channel BFFs: the customer’s channel when interacting with the business (aka the customer’s context).

Here’s a practical example to help solidify this. In the diagram above, “Order Management” is a business capability (Domain API). It’s about modeling the order lifecycle and its processes when an order status changes.

But, “Past Orders” is a customer journey (Experience API). Customers care about what they’ve ordered before as they may reorder these items again. To model this journey from an API perspective, we have the following customer needs:

• View a list of past orders GET /past-orders
• View a single order from the list GET /past-orders/{id}
• View accrued reward points for order GET /past-orders/{id}/rewards
• Search past orders GET /past-orders?query="The good restaurant"
• Mark order as favorite PUT /past-orders/{id}/favorite
• Rate order items POST /past-orders/{id}/item/{item-id}/ratings
• Fast Re-order POST /past-orders/{id}/reorder
• View order receipt GET /past-orders/{id}/receipt
• Download order receipt GET /past-orders/{id}/receipt/download
• Email order receipt POST /past-orders/{id}/receipt/email
• Customer support POST /past-orders/{id}/complaints

Notice that concepts such as creating an order or changing order status are missing from this list. These are purposefully omitted as they are concerns of the business, not the customer. They’re outside the boundary of “Past Orders” as a customer experience.

Here is another example. Menu management is a business capability (Domain API). It involves adding/removing menu items to/from restaurants, adjusting prices for menu items and setting price guardrails to prevent losses.

“Browsing” restaurant menus, however, is a customer journey (Experience API). It involves viewing restaurants nearby, filtering restaurants by category, sorting by ratings and popularity.

Now let’s see how this impacts the architecture.

How Experience APIs enable share-ability and reusability in the architecture.

In this section, we introduce “Browse” as an Experience API to the architecture and contrast it with that of the BFFs’ orchestration discussed previously.

Packaging the Browse journey into an Experience API

In this diagram, we shift the complexity away from the BFF and push it to the Experience APIs layer. BFFs now cater to specific channel needs as opposed to orchestration. They only decide what’s relevant to expose, taking the customer’s context into account.

Now, let’s consider the previous example from a non-functional lens. If we leave BFFs to orchestrate instead of Experience APIs, it means that each BFF will have to determine:

• How to run retry logic when timeouts or failures occur.
• How to slim down the experience when other services are unhealthy.

For instance, the business may decide to not show offers if the offer service is unhealthy. This still gives the user a meaningful “Browse” experience minus offers. Leaving the implementation of this logic to each BFF results in duplication and inconsistency of error handling.

Each BFF duplicating retry logic and failure handling

But, with Experience APIs, we tackle failure and retry scenarios within the “Browse API.” This allows us to serve the slimmed down experience from a single source of truth.

Browse API handling failure and sharing it with other channels via BFFs.

This reification of customer experience in the architecture is exactly what enables Experience APIs to become a shareable product.

The benefits and implications of using Experience APIs.

Adopting Experience APIs has many cascading benefits. We’ll discuss these benefits as they relate to:

• Total cost of ownership
• Scaling digital presence
• Team alignment
• Evolutionary Architecture

Total cost of ownership:

Businesses are increasingly looking to deliver new digital experiences and onboard new channels. But they struggle to manage the growing number of applications that support these experiences and channels.

The “write-once, share-everywhere” aspect of Experience APIs reduces development time and cost associated with adding new channels. Now, adding a channel only costs building its own implementation logic. Not re-building the orchestration logic again.

Scaling digital presence:

That same “write-once, share-everywhere” aspect also enables a consistent customer experience across channels. Because of this, Experience APIs improve speed-to-market when onboarding new channels. As complexity shifts to the Experience Layer, the design and development footprint of the channel layer becomes minimal. With this approach, organizations can scale their overall digital presence without too much friction.

Team alignment:

Today’s digital experiences are rich and complex. Yet, organizations still only think of channels as experiences and are organized around capabilities and channels, with no long-lived teams driving each unique experience.

A customer experience, however, cuts across different business capabilities and channels. As a result, making changes to experiences usually causes friction across teams and organization boundaries.

If we align our teams around the customer experience, changes will be made without causing that friction. Teams can independently work on their bounded experience without stepping on each other.

Experience-aligned Teams (Browse Team and Checkout Team)

Additionally, Experience-aligned teams have strong subject matter expertise of the customer. This customer centricity contributes to team happiness as they can see how their work directly impacts the customer. They are more empathetic to customer pain points since they’re not far removed from how customers engage with the product.

Evolutionary architecture:

Experience APIs aren’t an “all or nothing” approach. They’re evolutionary by nature. Modeling this approach and team structure can be trialed for a single experience before it can be rolled out company-wide.

Experience APIs also enable extensibility in service architecture. They’re not a replacement for Domain APIs, they augment them. This adds a much needed layer in the architecture that glues various customer touch-points together.

Lastly, Experience APIs are complimentary to patterns like Micro Frontends where teams work on independently developed and deployed front-end in a large ecosystem.

Closing Thoughts

• Mixing experience and domain logic often results in rigid architecture that cannot evolve to keep up with customer needs.
• Though it may seem counterintuitive, onboarding new channels requires focus on the customer experience … not the channels themselves.
• The idea behind Experience APIs isn’t necessarily novel. Lots of services are designed this way. Though they’re often referred to as business capabilities, with some exceptions².
• The name “Experience APIs” enables thinking of the customer and their needs first. It encourages thinking of APIs as shareable products.
• This naming also helps differentiate a true business capability versus a customer experience as they should be treated differently.
• Because of its dependency on the proper team structure, it’s difficult to realize this architecture without “moving and shaking” organizational boundaries. In other words, Inverse Conway Maneuver is certainly needed here. Inverse Conway Maneuver is a corollary to Conway’s Law that recommends forming team structures that lead to the desired architecture.

Acknowledgments

Big thanks to Smitha Ajay, Bruna Castelo, Megan Lusher, Lav Pathak, Cliff Morehead, Ibrahim Taha and Yujie Wu for reading drafts of this article and providing feedback.

Additional Reads

• Designing effective Experience APIs: Principles, Patterns, Anti-patterns.

Footnotes

¹ This is an abbreviated example. Surfacing the full-blown “Browse” experience will likely need other APIs like: Promos, Ratings, Delivery Estimates and Recommendations APIs to name a few.

² PayPal calls them Experience-based Services and APIs in their API Style Guide. Uber calls this a Product Layer (i.e: Request a Ride) within their 5 layers of Microservice Architecture.