API Driven User Experience

Written By Victor Paulsamy, Ingo Claro and Haozhe Chen

Integrating 3rd Party Reservation Tools

Bookable marketplace teams are making Groupon inventories bookable. Broadly, there are two types of merchants on the Groupon platform — one is connected via APIs and the other is non-connected; that is, their data is not connected to external applications to deliver experiences. Partner is a 3rd party booking tool provider with whom Groupon establishes deeper ties by making investments on both sides in API integration.

When we reimagined the next iteration of 3rd party integrations, it all came down to this most important question — what incredible benefits can we give to our merchants? The answer was simple and yet profound — empower partners to grow their business on Groupon. So we decided to put the partners in the driver’s seat with APIs specially designed for the partners to self-serve their integrations. The overarching objective is to enable the partners to integrate their reservation systems quickly and easily for their merchants to grow bookings on Groupon while still using the partner’s primary reservation solution.

In the self-serve integration, the partners implement only a few endpoints — defined in an API specification — for Groupon users to check merchants’ availability in realtime and create bookings from the Groupon consumer apps.

User Experience

Our Groupon Partner API is designed to help all sorts of different businesses to leverage the capabilities of the Groupon platform by presenting endpoints and webhooks which allow the partners to integrate their order and inventory management systems with ours.

One of our ambitions is to provide a standard API layer that supports the majority of partner use cases. With that in mind, we designed a set of generic APIs and solutions that are all-encompassing and flexible at the same time to address the entirety of Leisure in Things To Do (TTD) and Health, Beauty and Wellness (HBW) segments of the business.

Booking Experience for TTD

The TTD booking flow allows the customer to verify availability for a specific date and time, as well as supporting different kinds of availability (such as adult/child tickets). Booking prior to purchase allows users to locate an available time that works for the user’s schedule and party size before purchasing a deal.

Users select an available date, enter the details of the party size (for example, 2 adults), specify the type of tour/tickets for the deal (for example, “Entrance” or “Entrance with Nativity Facade tower access + Audio guide”) and a preferred time for the deal. If required, the users provide any requested additional information.

Booking Experience for HBW

The HBW booking flow supports post-purchase booking which allows users to purchase a deal at one time and schedule a booking at a later time. Users can select a location, a service, and a date and time for a booking.

Modeling and Implementation

Design Principles

When we model the APIs, we are following these principles:

• Extensibility: as the business evolves and new requirements are added to the API we would need to add those in a non-breaking way, by being backward compatible with previous integrations.
• Flexibility: The same solution can be adapted to multiple verticals, and it can support experiences on different clients, like mobile and web.
• Agility: We can easily iterate it and test different experiences.
• Simplicity: It is easy to understand, explain, and reason about; since partners implement the spec, its complexity is directly proportional to the cost of the integrations; that is, higher complexity increases time to market; the goal is to reduce it, however.
• Performance: We ensure great user experience by having the apps respond quickly to customers’ input.

API Modeling

Different actions possible with the API such as fetching the availability, completing a transaction (booking), updating states, etc. In this article, we are focusing on the availability API and how it supports, drives, and delivers the user experience.

The availability is consumed as a feed that Groupon caches to ensure a low latency interaction for searching and booking a selection. Booking UX is driven by this API to support the cases shown here and much more. Key components are Attributes, Questions, and the Availability itself. More details are below:

Attributes

Attributes are modeled the following way:

These attributes are displayed as selection widgets in the UI to filter the availability. This specification has the following features:

• selectionType indicates whether multiple values can be selected by the customer.
• category is optional and is indicating a special group of attributes that will have a special treatment in the UI. This can be further extended into new values in the future.
• writeups are used to provide textual values in different locales that will be displayed to the customer. These can also be extended in the future to add more capabilities in a non-breaking way.

The availability references the attribute values that they apply to, we will show how this works below.

Here is an example that powers the TTD screens above (party size and tour type):

Modeling Customer Inputs

We present additional fields and forms to request information, as questions, which will be associated with the reservation. In order to support a flexible questionnaire, we introduced a question schema.

• Based on the type of a field, we generate different components on the client UI. It can be extended if we need more components
• Supports client-side validation through constraints such as type, required, pattern, minLength and maxLength
• With the recursive fields, we support nested forms
• Fields can be pre-filled with values
• The hint and label are to generate helper text

An example showing how UI form is driven by the API

The Generated UI powered by the API above

Availability Segments

Segments are where availability is defined. It combines time and attributes. Additionally, they override some data if needed such as price and additional questions. This is helpful to model more expensive premium times.

This structure allows for greater flexibility since any specific combination of time and attributes can be specified; the drawback is that by being more specific, lots of data is needed and that is why we are consuming this data as a feed using a background job and caching it in our systems.

Here is an example of an availability segment for an adult entrance using a price override:

Availability Selection

As we have shown so far, the API specification is very flexible and enables different business verticals to operate with Groupon. Unfortunately, it requires a lot of data, since it can detail availability at the time slot level, normally it would require to have the product of all attribute groups times the number of time slots data points. For example, 1 month of availability with 10-time slots per day, 6 party size, 3 tour types, gives us 30*10*6*3 = 5400 segments in the availability feed and this grows as attribute groups are added!

Handling all this data in the client application (booking widget) isn’t very fast, the main problem is to determine the “from price” and available options according to the customer's selections.

In a naive implementation, we would keep a filtered list of segments (which starts with all of them), and each time the customer makes a selection, we keep the segments in the list that match that selection (eg: date matches or they have the corresponding attributed), then compute the from price from that list. Additionally, we need to detect which options aren’t available anymore (eg: after selecting a date and party size, some tours might not be available and need to be disabled).

The problem is compounded by the requirement of showing the “from price” of each visible option (each date of the calendar, each attribute). Note that as the customer is selecting, the “from price” of the next options might change, for example, after selecting 2 Adults and 1 Kid, we calculate the price based on that selection.

To minimize the computations done on the client, some of them are performed on the backend to ensure a great user experience with our product. When the client fetches the availability it gets the data it needs to render all widgets: dates with from prices and availability attributes, as well as the list of all segments.

The initial UI is rendered right away with the data provided by the backend, and while the customer is making their first selection, full availability is processed in a non-blocking way. The client creates a series of hashmaps and lists to make the filtering and each “from price” computation way faster.

As a next step, we are looking at ways to improve our API to see if there are ways to reduce the payload size and chattiness while retaining flexibility.

Summary

It’s magical when people work together. Building a strong team requires paying attention to team chemistry and it’s a big deal. We are a team of six to eight engineers empowered to solve problems our customers care about the most while orienting around problems — not solutions. We are consumed by passion for removing friction through a robust self-service platform, ensuring seamless booking experiences, and creating products and services to build deep and broad supply.

Intrigued? Reach out to us, we’re keen to connect with you and hear your ideas.