Coupling Up: Adding Business Value to APIs

Here’s a controversial statement: The API community has been so caught up addressing technical challenges that the most important API definition of them all has not yet emerged: a business value API. 

But let me step back a moment. As an architect for an event broker company, I spend a lot of time evangelizing, preaching, and droning on about the benefits of decoupling microservices from each other using… well… an event broker. Among its many fine qualities, decoupling aids with performance, error handling, agility and deployment. It’s awesome! 

However, when I think about creating a business solution — doing something that creates value — it’s all about coupling things: grabbing an application here, a function as a service (FaaS) there, toss in a couple on-premises microservices, and string them together somehow. In fact, the rise of microservices means that creating repeatable recipes that combine many different technologies and ensuring that they produce consistent outcomes is the reason IT exists. 

Figure 1: The Coupling/Decoupling Cycle

This makes the lack of focus on the recipes and the lack of a widely accepted, open-source spec to describe them more baffling. In short, what’s lacking is an open-source spec that:

• Focuses on achieving business outcomes.
• Encompasses a wide range of different interaction styles and technologies, particularly blending synchronous and asynchronous interactions.
• Moves beyond correlation or just grouping together of similar APIs to causation—this happens because this other thing happened first

Why do we need an API at the business value layer?

In addition to talking about decoupling constantly, I spend a lot of time thinking about how to best define APIs, especially within the AsyncAPI community. But outside of the minutia of the API world (which is important, too!) the focus immediately turns to the business use case. This has always been true but came through loud and clear in a couple recent situations.

Sussing out the Business Value of EDA with EventStorming 

Event-driven architecture (EDA) doesn’t emerge from the ether on its own. There have been multiple attempts to define a methodology for EDA, some written by me.  Recently, one methodology (not mine, sadly) has gained prominence: EventStorming. Alberto Brandolini, EventStorming’s creator, describes it as “a flexible workshop format for collaborative exploration of complex business domains… to design clean and maintainable event-driven software to support rapidly evolving businesses.”

There is an extensive, interesting process including vast numbers of sticky notes and reconfiguring your conference room furniture, but the output of an EventStorming session looks like this:

Figure 2: Example Output from an EventStorming Session

What do you notice?

• It incorporates multiple different events to understand how a business process works.
• That understanding depends on causality, knowing where the event come from, what came before it and what comes after?

Selling EDA with Use Cases that show Business Value 

I was recently invited to my first in-person business meeting in two years. It was fantastic: sitting in a hotel ballroom, eating mediocre bagels, shaking actual people’s hands (and sanitizing afterwards). But what I heard repeatedly in response to technical presentations: “This is great, but how do we sell it to the business.”

The answer was: “Find a good business use case and start small.” As an example, a master sales team flashed this slide up on the screen (it really wasn’t Acme Co, I’ve changed up some logos).

Figure 3: Example Proof of Concept Definition

By building out this proof of concept, the sales team proved the benefit of Solace and got the sale.  But first, the team had to document the interactions. What do you notice?

• Mixture of asynchronous and asynchronous APIs, custom and SaaS applications.
• All the components are tied together in a causal flow. Understanding where the transactions come from, what came before it and what comes after is key.

Recognizing, documenting, and implementing those elements was what provided value.

What does business value mean for APIs?

If the business use case is key, it makes sense to envision architectures as separate, but related layers of interaction: business, logical and physical.

The distinction between the layers are the questions that each aims to answer.

• Business layer: What is the sequence of logical interactions that occur to achieve a particular business outcome?
• Logical layer: How do applications and events interact with each other?
• Physical layer: What artifacts implement these logical interactions?

Given the importance of the business layer, it makes sense to thoroughly document it. Thinking about past projects, that documentation can take any number of different forms:

• Microsoft Word documents
• Markdown files in GitHub
• Excel spreadsheets
• JPEGs of EventStorming sessions
• PowerPoint slides

But while these solutions work for some teams, none of those solutions allow you to take that business-layer documentation that presumably you’ve spent a lot of time on and leverage it elsewhere.

What Does It Mean to be Event Driven? Open Your Mind and Unlock New Business Value!What is event driven? To transform into an event-driven enterprise and unlock new businss value, consider technology as only one piece of the puzzle.Read Now

What does an API for business value look like?

Standardized, human-readable documentation that can be leverage multiple different ways is the realm of the API. The logical and physical layers have multiple associated API standards:

• At the logical layer, you have AsyncAPI “Core”, GraphQL, and Open API.
• At the physical layer, you’ve got AsyncAPI Bindings (e.g. Kafka, Solace) and OpenAPI (e.g. REST of HTTP, webhooks, etc.)

There has been some progress in the business layer, but the lack of a single, mature standard has hindered enterprises. Without a standard way to document an end-to-end transaction flows, every enterprise must come up with its own non-interoperable solution — leading to things like the “JPEG on a shared drive” approach. And that’s a shame, because a business-layer API and associated tooling could provide real value including:

• Business use cases: Understand which components are integrated together to form a piece of business functionality
• Data lineage: Understand where data originates from and how it’s been modified
• Code generation: Create code that not only has the correct functions, but links them together in the right causal order
• Distributed Trace/Monitoring: Detect if a business process doesn’t complete or doesn’t follow the intended order of operations
• Environment Promotion: Define all the components that need to move to an environment to have a complete business solution.

The Path Forward

As I said at the beginning, business layer APIs have seen comparatively less attention than their logical and physical layer peers. There are some signs of life:

• The Cloud-Native Computing Foundation project Serverless Workflow has a very full-featured model (perhaps too complex for defining business level logic), but tooling and vendor support is sparse. Also, it is tightly bound to another CNCF project called CloudEvents, which makes it less appealing for those who haven’t adopted CloudEvents.
• Business Process Modeling and Notation (BPMN): the oldest of the bunch, has lost favor due to its complexity and lack of tooling support beyond large enterprise orchestration engines.
• Unified Modelling Language (UML): an open standard, but not easily transformed into code or imported into tooling, as there is no underlying API definition.

Conclusion

With the continued prominence of microservices and the rise of hybrid asynchronous/synchronous solutions, the need for a business-level API will only increase. The open source standards community will undoubtedly rise to meet this challenge, and the resulting opportunities will be remarkable.