What Event-based Architectures Mean for Application Integration

For the last eternity (about 5–10 years, in our short-lived memory), REST has been the dominating architectural style that developers aspired to. Event-based architectures are a new style that’s gaining popularity among developers, and one that has clear implications for API consumers and API producers.

If you’ve been using any API for a SaaS product in the past ten years, you will have come across examples of RESTful design. The basic principles of RESTful APIs: they are designed with client-server interaction in mind (you being the client, the API being the server), clients being stateless, in a cached, layerable system, which is using a uniform interface, where resources are being identified, and resources get manipulated through representations.

API providers that care about API design have to consider a number of questions, in particular:

  • What are the resources that my application is dealing with, and how do they get addressed?
  • How do clients manipulate these resources? I.E., what are the actions that a client can perform on behalf of a user?
  • What is a good, standardized way to represent resources? These days, the answer almost always is a variation of “JSON”.
What is the conceptual model of my application that I want to expose to consumers of my API?

The most important question boils down to: “What is the conceptual model of my application that I want to expose to consumers of my API?”. The conceptual model can be described in two ways:

  1. Through the things that the application is managing.
  2. Through the actions that users can perform on these things.

Event-based architectures, in as far as they apply to application integration, are largely an extension of the prevailing model, with a couple of additions and changes. WebHooks (as one of the most important incarnations) are using HTTP, JSON or XML and will feel very familiar to developers that know REST APIs. A couple of notable differences:

  • For the most part, WebHooks turn the client-server model around. Where traditionally the API provider has been the server and the consumer the client, with WebHooks, both sides are client and server.
    Registering a WebHook with an API provider makes you the client, but when the API provider is sending the WebHook, it is expecting you to serve as the server.
  • Resources are still the focal point of API design, but in most event-based architectures they become the topics that can be observed.
  • Finally, while the key question for REST APIs has been “what can the API consumer do to resources”, in event-based architectures it should be modified to “what is being done to resources, that a consumer would care about?”.

Let’s say you are building a pet shelter application. Your application is managing resources (pets looking for adoption) and you have the following resources and methods:

  • GET /pets/ lists all pets currently in shelter
  • PUT /pets/{name} adds a new pet with the specified name to the shelter
  • GET /pets/{name} gets information about the pet name
  • POST /pets/{name} records that a visitor has expressed interest in adopting a pet
  • DELETE /pets/{name} removes a pet from the shelter (e.g., a pet got adopted!)

Now, what would it look like to add an event layer to this API? We would look at the events, or the types of activities that are done to the shelter and the pets, and the key state changes. This could include events like:

  • admitted — when a pet is admitted to the shelter
  • adopted — when a pet is adopted out from the shelter
  • visited — when a pet has been seen by a visitor
  • capacitychanged — when the shelter’s capacity has changed (or is full)

In the next step, you would look at filtering options for events, so that API consumers have a better way of discerning what to be notified of. You don’t want to overload your consumers or push the burden of making additional API calls to determine if the resource that got updated is really the one they are interested in.

In our example, a good candidate to filter would be type, so that you can get notified only when a parakeet is available for adoption, and leave dog and cat notifications to other people.

Event-based architectures allow you to find out immediately when the parakeet of your dreams is available for adoption.
This shift from the active voice to the passive voice, from “do to” to “done to” is a highly important shift for both API providers and API consumers.

API providers need to think through what the meaningful, actionable and interesting changes are that their application is performing on the managed resources, and allow visibility into those events.

API consumers need to be clear what they want to listen to, and what changes they can act on. Once you know, talk to your API provider and ask for the interesting events.

What will you listen for?