Introduction
As enterprises increasingly look to distribute and react to information in real-time – i.e. become event driven – they face the challenge of giving application architects, developers, business stakeholders and even third parties the ability to find and make use of all of the real-time information that event-driven architecture (EDA) and event-driven integration enables.
Today developers often struggle to find and consume assets related to EDA, such as event streams, event-driven applications, etc. –because everything is spread across platforms and technologies, each with its own catalog or portal, and its own way of handling access control. This makes it tricky for developers to find the assets they need to even start building applications that deliver value to the business.
The natural progression here is to create the equivalent of an API for events. This is an emerging concept, and several terms have been coined, such as event-driven API, evented API, and event API. At Solace we’ve embraced the third option, and refer to them as “event APIs” both in our marketing materials and within our event management product PubSub+ Event Portal.
Event APIs and event API governance are an emerging space, so let’s shed some light on the key terms.
What is an event?
The word event is used two ways in context of event-driven architecture:
- An event is a change of state, or more broadly anything that can be noticed and recorded by an application or device and shared with other applications and devices. All the things that happen within and to your enterprise are events – customer requests, inventory updates, sensor readings, etc.
- We also use the word “event” to refer to the messages that alert other systems about the “event” that has occurred, such as the state change event described above as well as command, query or document messages.
When an event occurs, it is typically delivered to interested parties asynchronously via the publish/subscribe message exchange pattern. Simply put, the sender of an event actually sends it to an event broker, which takes care of routing and delivering it to recipients that receive events matching their interests (subscriptions) from the broker whenever they are ready (listening). The publisher is generally unaware of who receives the information, i.e. what applications, how many of them, where they’re running, etc. And subscribers don’t need to know or care where the information they want, and get, is coming from.
What is an event API?
An event API is the means by which developers can give the application they’re building access to data flowing as part of an event stream. Event protocols such as AMQP, MQTT, Webhooks and Websockets define the event exchange pattern – one can send or receive an event – but there is no standardized way to convey the intent or behaviour. Is the event an “update” or “delete”? Is it related to a resource? What family of events does an event belong to?
These questions are hard to answer for an outsider as they don’t have in-depth knowledge of our internal domain model and the services and systems that make up our domain.
There isn’t a widely accepted, implicit convention for how to identify events as relating to the same resource, as opposed to RESTful APIs. (You can find more in-depth discussion of this difference in “The Case for Event APIs and Unified Event & API Management”.)
Therefore, we need to group events into event APIs and document these event APIs carefully. Learn more about how you can create and manage event APIs in Event Portal.
What is AsyncAPI?
AsyncAPI is an open standard that defines an event API for the purpose of documentation and usage in tooling, e.g. for code generation.
The AsyncAPI Specification is an open source project that describes message-driven APIs in a machine-readable format. It’s protocol-agnostic, so you can use it for APIs that work over any protocol. AsyncAPI defines a set of fields that can be used in an AsyncAPI document to describe an application‘s API.
AsyncAPI is to event APIs what the Open API Specification (OAS) is to RESTful APIs. There are quite a few similarities in these standards, which makes it easy to understand AsyncAPI when coming at it from an OAS background.
You may have noted that the above mention of “application” – there are multiple ways to interpret “an application’s API”.
It could mean “the API that describes how clients can interact with an application” – in Solace PubSub+ Event Portal we call this an event API. Once you have created an event API in Event Portal you can download its open standard AsyncAPI definition, and there are other, more useful ways to make Event APIs consumable for any developer who want to use them.
Another interpretation is “a specification that describes how an application interacts with an event broker”. In Event Portal we call this an “application” and of course it can also be described with an AsyncAPI.
(For a more detailed discussion of applications and event APIs in Event Portal head over to “When to Use Events or Event APIs; Explain it Like a Muppet”.)
What is an event API product?
The term “API product” is widely used in the traditional API management context. It is a collection of APIs that are packaged together and made available to application developers. API products can be used to repackage existing APIs in different combinations to provide a customized experience for clients so they can be used to solve business problems and create a smooth experience for users. Often the approach to design APIs and API products with audience needs as a starting point is called “outside-in”.
When creating API products, it’s important to consider the user experience and package the product in a way that makes sense for the target audience. Google Cloud created a video called “The API Mindset” that provides a detailed explanation and examples like this:
API products also define policies applicable to its audience such as throttling or quotas. API Products may contain plans or usage tiers that define policy restrictions such as the number of requests per second.
Just like API products, event API products add a layer for packaging and marketing event APIs to developers and the same principles apply as outlined above for API products.
An event API product lets companies package multiple event APIs relevant for a specific use case or target developer profile.
Just like with API products, event API products add connection information and define policies, quality of service and connection details to event APIs. For example, a company may want to define event retention policies like reserved persistent storage quota or “time to live” of events.
For more details on the concept head over to “Event API Products surface APIs to Developers” or find out how Event Portal supports event API products.
What is unified API management?
Once you look at your system through an event API lens you realise that you need to apply API management processes to them with two main concerns:
- Event API lifecycle management requires tailor made capabilities. Event APIs are similar to RESTful APIs but not the same.
- Developers expect to find event APIs in the same place – a developer portal – where they find other APIs. Ideally even as a component of an API product alongside RESTful APIs.
This diagram shows the idea of unified API management at a high level, i.e. managing RESTful APIs and event APIs with a unified platform.
You need three components to successfully manage event APIs:
- An event portal for the back-office work of creating, cataloguing and governing them.
- A front-office tool where you can curate and expose all your APIs: RESTful, event, and others.
- A storefront, like a developer portal or marketplace, where developers can find and access event APIs and/or event API products.
When it comes to including event APIs in front-office API management and developer portals, a new breed or at least an evolution of existing API management solutions is required. The solution must bring together all kinds of API styles and provides overall management and governance capabilities. We call this unified API management, you can read some more thoughts on this subject in my blog “The Case for Event APIs and Unified Event & API Management“.
There are several different flavors of unified API management that all bring event and RESTful APIs together. They commonly allow to manage and govern multiple APIM deployments from the same vendor – e.g. in a hybrid cloud environment – or from multiple different vendors.
Event-native API management refers to API platforms that have built in event API management capabilities and support event protocols on their API gateways (often HTTP based Web protocols such as Websockets, Webhook, Server Sent Events).
The blog post “Architectural Patterns for Event APIs and Unified Event & API Management” explores these approaches in more detail.