When to Use Events or Event APIs;
Explain it Like a Muppet

In this blog post I’ll describe how PubSub+ Event Portal uses events and event APIs to describe event flows between applications, and then help you understand when to use which based on a few concepts that are so simple I’ll explain them in a way that’s “Sesame Street simple” with the help of everybody’s favourite sometimes-superhero Grover.

• One, Few and Many
• Near and Far
• Complexity and Cost

Introduction to Events, Event APIs, and Event API Products

In PubSub+_Event Portal, events are the basic building blocks for everything. Events are published and consumed by applications, and they can be combined into event APIs.

• Events declare a topic and payload, but they do not specify their intended use – are they to be published by an application (or service) or meant to be consumed (subscribed to)?
• Event APIs combine related events into an interface that also determines the operation– publish or subscribe – allowed to the API’s clients.
• Event API products add information about the physical usage of the event API, e.g. the service level agreement, broker location(s) and protocols clients are supposed to use to connect. Developers can register applications and request access to event API products. Event API products are typically made available to developers in a place that they are already familiar with, where they go to find other types of APIs. In existing developer portals, APIM platforms (e.g. Gravitee and their API federation feature) or API marketplaces.

Applications and their event flows represent a concrete instance of an application, whereas event APIs are like an abstract, reusable interface that could be used by several different concrete applications or services.

Example

Picture a bank or financial institution. It is likely subject to regulations requiring reporting of specific type of transactions to authorities – bank transfers, stock or fund buy and sell orders, interest payments. The reportable transactions may be further qualified by amount, instruments – i.e. specific stocks and payer/payee.

You can model this in Event Portal either as an application that consumes bank transfer, stock or fund orders and interest payments events. You can also attach conditions to event flows using filtering rules on the event topic – for example, a specific transaction amount threshold.

Or you could create an event API that allows clients to consume these events so that application developers can get access to the event API – this allows multiple, local development teams in different jurisdictions to build a compliance reporting application based on the requirements in their location.

Decision Factors for When to Use an Event or an Event API

One, Few and Many

The first decision factor is how many applications you’re talking about, and how many kinds of applications. How many applications are you talking about? And how similar are they? How many of the same kind of each application are there?

My blue buddy Grover of Sesame Street fame did a good job explaining the notion of one, few and many here:

Suppose you start out with two event-driven microservices – you can design a set of events that the services use for communication. Then you can design the service interaction by modelling the Applications and event flows in Event Portal. Now you have one of each kind.

Let’s say one of the services is a bank’s regulatory compliance reporting engine. Say subsequently you are asked to add a reporting engine for each country or jurisdiction the bank is operating in. You’d create a new application in Event Portal, add the required event flows and modify the existing event flows so that events are consumed by the correct reporting service. Now you have a few of each kind. And that’s fine.

But what if you need to create fifty more compliance reporting services for additional countries, states or other jurisdictions? Now we have many of one kind. Too many to treat as individual applications with their own event flows – we need to be able to treat these all the same and ensure they support the same set of event flows (in other words – use the same event API).

Near and Far

Another important factor is how closely held the creation and operation of your applications is – near or far? Where is the application that needs to use your events? Who owns it? Who owns its tech stack, lifecycle management, software development processes?

Again, my fuzzy blue friend Grover broke it down in the simplest terms:

Suppose you are doing the right thing, and everybody within your domain – your sphere of control – uses Event Portal. All of your designers and architects model events, applications, and event flows in Event Portal, and use it to manage both the lifecycle of all these components and the runtime configuration required for the applications.  Processes are built around Event Portal (e.g. CI/CD Integration), and tools are provided to your developers to get event-driven done quicker and more easily.

The answer to the questions above is “near” because you and the teams around you who run the applications, own event definitions, use a common tech stack and follow the same software development lifecycle.

However, there always are applications in other domains that you don’t control that require communication with your domain. These domains manage the design and life cycle of their applications and all their other assets with whatever processes and methodologies they have settled on.

These could be anywhere in your organization, like a subsidiary that develops its own applications or lines of business that outsource development. Or even domains outside of your organization altogether, e.g. suppliers, partners, customers. They’ll do stuff their way. That’s “far”.

Have another look at Grover in the picture above – when he is near, we can make out a lot of distinctive features, but when he’s far away we can barely make out that it’s him. When developers are far away from our domain they have little understanding of the details of our domain. When you provide them with a curated, well-documented event API they can use your events without understanding the internals or intricacies of our domain.

Cost and Complexity

The third decision factor is cost and complexity. Event Portal allows you to do anything related to events and applications in one place., but when it comes to event APIs the picture is a little different.

Event Portal supports the design and lifecycle management of event APIs, the packaging of event APIs into event API products and its associated plans. However, the developer experience for consuming these event API products is provided in a place where the developers already work: a developer portal or API marketplace where they find the other types of APIs they are familiar with.

Consequently, the overall solution becomes more complex and potentially more costly. You may be able to use existing Event Portal integrations for Gravitee  APIM Federation, WSO2 APIM or Axway API Marketplace. Or you might have to create a suitable integration with your existing developer portal – for example, develop custom plugins for your backstage.io portal or whatever technology your developer portal is based on.

Breaking Down What to Use When

	Events	Events	Event APIs
	Events	Events or Event APIs	Event APIs

One of a Kind

Modelling events and event flows of applications in Event Portal is useful in any case where all applications are one of its kind. Even if the application is far away – outside of your domain – you’ll be able to manage somehow. You can liaise with the application owner and make their life easier by creating an application and its event flows for them in Event Portal. You can then provide them with their application’s AsyncAPI as a means of documentation and basis for their code generation, if they wish to. Once you get to know them better, you may even give them programmatic access (via a REST API) to pull their AsyncAPI or request access for their application to be configured on event Brokers.

Near and Few of a Kind

Now we are adding a few applications that are the same kind and the application owners are near – we can use Event Portal to model these applications and their flows. We need to make sure that the event flows are uniform across the applications. Maybe there are slight variations between the event flows of these applications, and we can easily accommodate these as well.

Far and Few of a Kind

What if there are a few applications but their owners are far? Going back to the banking example – maybe it only operates in half a dozen countries. This is where it becomes tricky – we can still model this “same kind” of applications in Event Portal. But the manual processes – like designing applications and managing change on behalf of the owner – become cumbersome.

We may be able to accommodate this scenario initially but the more external applications we must manage the harder it becomes. Eventually, the application owner may consider our governance process a hindrance to getting their work done.

Therefore “Far and few” can be the tipping point towards event APIs that allow application owners (developers) to register applications themselves and declare them one of a kind by requesting access to event APIs.

For this scenario, you need to look carefully at in terms of costs and benefits of using event APIs. Even though usage of event APIs might be desirable from an organizational and technical point of view it may be cost-prohibitive to integrate a Developer Portal for a small number of “far” away applications.

It may be more economical to hold on to using events until “few” becomes closer to “many”.

Many of a Kind

Once you are dealing with “many” then near or far doesn’t matter. You must deal with so many applications that it is no longer feasible to model each application with its event flows while ensuring it has the same event flows as any other of its kind.

Uniformity across many applications always requires the use of an interface definition – an event API – and the ability for each owner to register their applications without our (or with minimal) intervention.

Conclusion

When you look across your domain as well as outside of its boundaries there’s probably applications that are one of a kind (or one of a few) and others that there’s many of the same kind.

It is also inherent in event-driven architecture that you often want to fan out (or funnel) events – you want to distribute events from a small number of publishers to many subscribers or route events from many publishers to a small number of consumers.

So you’ll most likely need to use both events and event APIs, and I hope this post has given you some easy-to-remember guidelines to help you use the right approach for each use case.