5.13. Event-driven APIs

Based on the article ‘Event-driven APIs’ (SIVI AFS Magazine December 2024)

From REST APIs to event-driven APIs

In today’s data-driven world, companies want to collect and analyze real-time data to improve the customer experience and make better decisions. APIs have become an indispensable part of this – as may be known by now.
Traditional APIs, such as REST APIs with JSON, work according to a request-response pattern. The client sends a request to the server and then waits for a response. This pattern can be synchronous or asynchronous: with a synchronous approach, the client receives an answer immediately, while with an asynchronous approach, some delay is possible. REST APIs mainly focus on retrieving information, with the client explicitly requesting specific data and the server providing it.

Event-driven APIs work differently. They use events, such as ‘policy closed’ or ‘address changed’. Instead of an explicit request, a party sends an event message when a change occurs. The communication is by definition asynchronous: no direct response is expected, only a confirmation of receipt. These APIs are designed to report changes, not to request information. A major advantage of event-driven APIs is that they are often more efficient and scalable, which can reduce the total cost of ownership. They are particularly useful when a party simply wants to indicate that something has happened, without needing direct feedback.

Efficient use for relevant change

Event-driven APIs operate within an event-driven architecture, in which events drive communication between systems or applications. This architecture is particularly suitable for environments where status changes occur frequently and systems must remain disconnected. The sending party shares an event, e.g. ‘policy closed’, and other systems receive this without any direct dependencies between the systems. In fact, the sender of the message does not care what the recipient does with the message. This makes the solution more scalable and efficient, especially with large amounts of data or the need for real-time updates. In contrast to REST APIs, where a client must periodically retrieve data (polling), an event-driven API automatically sends a message as soon as a relevant change occurs. This eliminates the need for continuous polling or batch processing.

Technical operation of event-driven APIs

in case of an event-driven API, the sending party publishes a message on a channel. Receiving parties, subscribed to this channel, automatically receive these messages. The distribution of messages is handled by a message broker: an infrastructure that is responsible for routing events to the correct recipients. Examples are systems like RabbitMQ, Kafka or AWS SNS/SQS.

Example: new policy notitication

In the insurance domain, there are many situations in which an event-driven approach works better than the classic REST API. Suppose an advisor has taken out a new policy and wants to pass it on to the insurer.
With a REST API, the advisor (acting as a client) approaches the insurer’s endpoint with a request to register the new policy. The insurer (the server) then sends back a direct response, for example a confirmation that the policy has been successfully registered. The advisor must wait for this response before he/she can continue. This request-response pattern also requires an active action from the advisor to call the API.
In an event-driven API, this works differently. The advisor publishes the event “new policy issued” on a pre-agreed channel, such as the ‘policies’ or ‘contracts’ channel. The insurer subscribed to this channel, automatically receives a notification when a new message arrives. This is where the advisor’s responsibility ends: he/she does not have to wait for a response and can immediately continue with other tasks. The insurer then processes the messages at its own pace, for example by using a queue in which all received policies are stored. This offers flexibility, because the processing of the messages is independent of the moment they arrive.
Event-driven APIs therefore ensure that systems can work independently of each other: the sending party does not have to take into account the capacity or status of the receiving party. This makes the process more scalable and efficient, especially in scenarios with many messages or peak loads.

Processing through the SIVI AFS API framework

In the current SIVI AFS API framework, REST API is the base. This also means that the function table is set up with request and response in mind. There is no need to change this. Where request and response are the norm, the current function table remains leading. Where an API does not necessarily require a response, SIVI will introduce an extension to the function table in 2025 for functions that can also take place event-driven.
As an example, below is a subset of event-driven functions. As with the REST functions, we have divided these into clusters, such as contract, loan and party. For each cluster, we distinguish operations and variants, which determine what the API definition looks like. For event-driven APIs we therefore see in fact the same table layout as for the REST APIs, where the payload of functions is also based on SIVI AFS structures such as the policyStructure, loanStructure and masterAgreementStructure:

No endpoint but channel

In case of event-driven APIs, we no longer talk about a path or endpoint, as we do with REST APIs, but rather about a channel. If we extend the comparison further, the channel is essentially an ‘endpoint’ where messages are published. The receiving party can subscribe to a channel to receive updates about specific types of events, such as ‘new policy’ or ‘loan updated.’ This subscription is technically managed using a message broker, such as Kafka or RabbitMQ.
Another key difference from the REST approach is that a channel is typically set up in a ‘broader’ way. The distinction between different types of events—such as a new, modified, or canceled policy—is not reflected in the channel itself. With REST endpoints, these differences are often explicitly defined, such as /policies/new for new policies versus /policies/changed for modified policies. In event-driven APIs, the receiver still needs to distinguish between event types (e.g., new or modified), but instead of extracting this information from different endpoints, they receive it directly as metadata within the message parameters. These parameters specify, for example, whether the policy is new or has been modified, making event processing more efficient.

Specifications: from OpenAPI to AsyncAPI

For REST APIs, OpenAPI has become the standard for defining and sharing specifications. These specifications make it easier for developers to design, document, and implement APIs consistently. Fortunately, for event-driven APIs, there is a similar standard: AsyncAPI.
AsyncAPI, which originally started as an extension of OpenAPI, provides a framework for describing event-driven API specifications. Like OpenAPI, it helps developers, architects, and analysts better understand and implement APIs. The major advantage of AsyncAPI is that it supports multiple communication protocols, such as Apache Kafka, RabbitMQ, and WebSocket. This allows organizations to choose the technology that best fits their infrastructure while maintaining uniform specifications.
In 2025, SIVI will explore how it can support organizations in using AsyncAPI. This includes developing guidelines, best practices, and potentially tooling to simplify the creation of AsyncAPI specifications.