Event-driven Architectures
Most people, if asked what they consider an API to be, would immediately think of a JSON-based, synchronous API over HTTP – they’ll be thinking of a RESTful API. This type of API has existed for the past 20 years and can be found throughout virtually all Integration solutions.
However, Integration Architects are becoming more appreciative of Event-driven architectures as they see the benefits of such solutions. This has increased the use of eventful APIs (or message-based, asynchronous APIs). They provide specific capabilities not fulfilled by traditional RESTful APIs.
An Eventful API does not require a synchronous response to a request. The APIs request is effectively fired off and then forgotten about. There is no waiting for a response, and a response is unnecessary.
There are two primary use cases for this approach.
- There’s an extremely high number of requests (such as a data stream entering a trading platform). Where processing and returning responses are of little consequence.
- The transaction is long-lived (possibly updating multiple systems in the process), so waiting for a response is not practical.
The diagram below covers a clear, high-level view of Event-Driven architecture. This is purely for illustration purposes. Here, Producers publish Events (messages) to particular Channels (queues) that are defined within an Event Broker. Consumers subscribed to certain Channels will then pick up these messages from those queues.
The emergence of AsynAPI
Until recently, there has been much tooling to help support the lifecycle of RESTful APIs: standard specifications, design platforms, testing frameworks, etc. However, the equivalent hasn’t existed for Eventful APIs, making the whole experience of building such an API much less consistent, demanding greater knowledge with additional skills.
With the development of the AsyncAPI specification, some of what is available for developing RESTful APIs is now available to EVENTful APIs. The specification, much like OAS and RAML (used in developing RESTful APIs), is of a human and machine-readable format and describes the interface of an Eventful API. As a point of note, it is actually open-sourced and based on OpenAPI, so those with either OAS or RAML knowledge would find it relatively intuitive.
Interface Structure
The structure of the specification is familiar to those with OAS or RAML experience. The salient aspects of the specification are detailed below.
The first line required in an interface specification details the version of AsyncAPI being used.
| asyncapi: ‘2.0.0’ |
Info
This is also required and can be viewed as the Header of the EVENTful API. It provides basic API documentation, such as title, description and version.
| info: title: sales-order-async description: This api processes Sales Orders. version: ‘1.0.0’ |
Servers
This Object provides information on the relevant Event Broker servers. Although this Object isn’t mandatory, it provides useful documentation. Information such as the Transport protocol and version of that protocol being used, the server’s URL and any Security Schemes being actively applied to the endpoint is specified here. Note, this isn’t restricted to covering only one Server environment (i.e. Production) but can be used to detail all other environments, if needed (i.e. non-Prod), to aid developers.
| servers: Dev: protocol: amqp url: amqp://broker.mycompany.com description: Development Instance security: – user-Password: [] |
Channels
Here, we see equivalent information to the Resources and Methods as defined for RESTful APIs; these being the Channel names and the Operations available to those channels. Note that for RESTful APIs, we have HTTP verbs to describe the different operations, for Eventful APIs, only two actions exist – Publish and Subscribe.
| channels: sales-order: publish: message: $ref: ‘#/components/messages/Sales_Order_Notification’ |
Components
This element is also not mandatory but is useful. It can be used to define additional properties, such as the applicable Security Schemes. It can also hold reusable fragments relating to the message structure, such as fields within the message.
Note, this is not a complete list of what can be held here in this Object – just an illustration of what might be useful.
| components: securitySchemes: user-Password: description: Username and Password authentication. type: userPassword messages: Sales_Order_Notification: contentType: application/json headers: type: object description: Message header properties: orderId: description: ID of the Sales Order type: string orderItem: description: Item ordered type: string orderAmount: description: Cost of the Item type: string |
Anypoint Platform
It’s now possible to create AsyncAPI specifications within Anypoint Platform. This feature is integrated into the Design Center functionality. Creating an AsyncAPI interface is no different than creating a RAML or OAS interface – choose the required option when starting.
As you would expect, the API documentation is rendered in real-time to match the code (as you have become familiar with when using RAML and OAS). It is also possible to reuse existing Datatypes and import them into new interfaces, meaning they need to be defined only once and used in synchronous and asynchronous APIs. The API interface specifications can also be published to Anypoint Exchange, like another asset, and so becomes discoverable – a key feature of Exchange.
However, what is not yet possible is the ability to scaffold projects in Anypoint Studio based on a specification, nor is it possible to apply security and governance from the API Manager.
One final point to note is that the version of the AsyncAPI specification that Anypoint Platform is compatible with is version 2.0.0 (this isn’t the latest).
Conclusion
The ability to create AsyncAPI interfaces is a welcome and much-needed addition to the tooling incorporated into the Anypoint Platform. Giving Architects and Developers a more seamless method of embedding Eventful APIs into their Integration Solutions.
However, the implementation for Eventful APIs does not yet provide the whole suite of tools that are currently available to RESTful APIs (such as oversight from API Manager). I eagerly await and will be looking out for further enhancements from MuleSoft.
To discuss your API approach and learn more about Eventful APIs, get in touch with Devoteam to learn more.
References
- MuleSoft AsyncAPI documentation:
- Main AsyncAPI site: