Manage Your APIs Like a 4-Star Restaurant

This blog is part of a four-part series.

1. Creating an API-First Culture and Company (Part 1)
2. Creating an API-First Culture and Company (Part 2)
3. Manage Your APIs Like a Four-Star Restaurant (this post)
4. How Platform Ops Teams Should Think About API Strategy (Part 4)

A renowned destination restaurant, like Benu in San Francisco or Guy Savoy in Paris, is truly a sight — and taste — to behold. The service is impeccable with each plate of food structured to bring out waves of flavors. Meals are tightly sequenced and spaced. Walk into the kitchen, and you are likely to see a clean space where the cooks and chefs move in harmony as though they were engaged in a secret dance. When a rush of diners enters, the front-of-house staff know they can redirect these patrons to the bar for a tasty bite and a tipple. Above all, the entire dining experience is tightly controlled, managed and optimized.

You probably don’t want your API team cooking a chocolate soufflé or scrubbing dishes, but the operation of a fine restaurant has uncanny parallels to API lifecycle management. From the test kitchen to line cooking, and from management of suppliers to making sure that customers without reservations can’t sneak in or that the credit card payments aren’t fraudulent, the multistep, multimodal business to make a restaurant hum like a well-played symphony demands planning, collaboration, coordination and a set of high standards for delivery and presentation.

Test Kitchen: API Collaboration and Design

The test kitchen is where the magic starts. In this collaborative space, the restaurant chef and team gather to try out new recipes, tweak existing ones and figure out how to keep diners wowed.

In the parallel technology world, the chef du API might go by different titles such as “Director of Engineering for APIs” or “VP of Product, APIs and Integrations.” They work with Platform Ops or DevOps teams to first create a high-level architecture for an organization’s APIs. Then, they devise more specific rules and conventions, like recipes. The API workspace is a collaboration. On an API publishing suite such as SwaggerHub or Postman, API recipe libraries are stored and team members can scoop out existing, vetted and documented APIs — such as GIS, block storage, or payment processing — to use as part of compound and complex applications.

Production Kitchen: Where Applications Come Together

On the line, the tested recipes are assembled from ingredients and base recipes (stock, glaze, etc.). In some instances, the ingredients are raw and need to be prepared — think fruits and vegetables. Some ingredients come partially prepared by someone else, like a fishmonger who sends filets of salmon or are entirely created by another organization, such as bottles of wine.

These elements can be compared to first-party code (made from scratch), microservices and internal APIs (partially prepared), and external, third-party APIs (created elsewhere). Without the compound application (the entire meal), each small application is just one course. Eaten together, the combination of courses and drinks create the restaurant experience — the user experience.

The kitchen staff, like an application development team, assembles the various ingredients outlined in approved recipes to create beautiful plates of food. In the digital world, we get to “eat” the output of applications by consuming images and video, or by using a CRM and video conferencing tool.

Expediters and Runners: The API Gateway

The expediter stands at the head of the kitchen. They make sure incoming diner requests are filled in a timely fashion with outbound plates staying top notch. The expediter is the equivalent of an API gateway ­— applying policies, monitoring traffic, and ensuring all the rules are followed. Outside the kitchen, runners bring the food to the waitstaff for delivery to tables. These runners are akin to load balancers and ingress controllers, which work closely with API gateways to ensure customer requests are filled in the correct order, ending up at the right places.

Front of House and Waitstaff: The Restaurant Load Balancer

The front-of-house staff at skilled restaurants have a knack for handling customers and keeping them happy. Front of house is also the gatekeeper, making sure that anyone attempting to secure a table on a busy Friday evening actually has a reservation. The front-of-house team also understands which customers are regulars — those who can get a seat no matter what and are treated to white-glove service.

In API management, the front of house would be the load balancer keeping the restaurant from being overwhelmed by traffic and making sure that only verified traffic can enter.

The waitstaff manages the experience for the customers, both the restaurant’s face and personality. These folks advise which ingredients are freshest, ensure that plates arrive at just the right time and send back any food that a customer rejects with explanations of what went wrong. They are like an API observability layer, helping the kitchen understand what’s happening with their users while identifying any trouble spots and poor performance. If a customer requests a change or if a plate comes out looking messy, the waitstaff deals with the customer issues.

Delivery Services and Packaged Products: The External API of the Restaurant Kitchen

With DoorDash deliveries of sushi from Omikase, or Mission burritos from Papalote being constantly rushed to hungry San Franciscans, restaurants are clearly seeking revenue sources beyond their dining rooms. The COVID-19 crisis has highlighted the need for delivery revenue and the benefits of creating retail products with longer shelf lives to be sold in store and online.

Deliveries and retail products are the external APIs, packaged for consumption by partners or other channels that a restaurant might not control. In fact, one of the fastest-growing restaurant types in recent years are ghost kitchens, which only sell to delivery services. These are the Twilios of the restaurant world, where the external service is the entire business. Our previously mentioned expediter is also in charge of verifying that these external demands are anticipated, planned for and met.

Restaurants may even deal with malicious attacks on their external APIs when a delivery service adds the restaurant to its stable without any agreement or notice. This can cause unexpected spikes in demand and could also compromise customer experience — for instance, if the meal is not delivered with care or in the right type of thermal enclosure.

Life Cycle of Recipes and Ingredients: Managing API Life Cycles

Just as technologies and companies deliver applications, restaurants evolve and change to survive ­and, ultimately, thrive. Customer tastes change with the times — Spanish whites are hot one year, Austrian Rieslings the next.

API architecture leaders have a similar job: making sure that APIs conform to modern requirements, upgrading them as necessary, and sometimes adding entirely new forms of APIs, like GraphQL. At the same time, restaurants must maintain the treasured recipes its regular customers adore ­— these can never be retired. The best kitchens are able to prepare almost any classic recipe for a regular. This is like the critical backward compatibility of APIs. It’s vital to be able to gracefully deprecate older versions without completely erasing or eliminating them from service.

Improve Your API Game by Learning to Think Like a Great Chef-Owner

For most complex technologies, it’s difficult to know where to start with APIs and how to build a culture and operational facility to make a great API-driven business. Food for thought: Great chef-owners have a grand vision ­of aesthetic and taste before they spend time in the test kitchen. First, they create the architecture. Next, they build the grammar and rules for their food creations. They work closely with the sommelier, pastry chef and purveyors of all wonderful ingredients to curate the elements that deliver the most in-demand and delicious building blocks of a great meal. The chef-owner tests then perfects ­— moving from a test environment to a production FoodOps. The chef-owner is always in close touch with everything happening in their establishment, an observability approach that mirrors the needs of site reliability engineers, AppDev teams and anyone else tasked with performance.

The chef-owner creates the rules for external API consumption, keeping consultation with internal teams to make sure that nothing is left on the table in terms of idle production capacity. Then, when they sense the customers need something new, the chef-owner looks at the APIs of their business and decides what needs to be upgraded — raw ingredients or first-party code (veggies, fruits), microservices and internal APIs (stocks, glazes, ganaches, filet of salmon), or third-party APIs (wine). The chef-owner is also constantly looking for ways to repackage the potential products of a restaurant into something that other channels can consume, in exchange for much-needed marginal revenue.

Lastly, great chef-owners empower teams to put the chef-owner slowly and gracefully out of work by taking over all the above responsibilities, freeing that chef-owner to think big thoughts about the future of food. The very best restaurants can survive and thrive when a chef-owner moves on to another venture. The same is true for API programs if they are built on a solid foundation and keep customer needs front and center. Just like a great restaurant must start with great ingredients, a resilient, adaptive business must start with great applications. Today, that means great APIs. Bon API appétit!