API-First with AsyncAPI
Originally published at https://zenwave360.github.io.
If you are familiar with OpenAPI and OpenAPI Generator API-First workflow:
- First write the OpenAPI definition, collaborating between API providers and API consumers.
- Then use OpenAPI Generator, either the maven plugin or a CLI, to generate some DTOs and interfaces from your OpenAPI definition.
- Implementing the generated interfaces you can create a service for the API.
- As a client, you can use generated the interfaces to consume the API with some HTTP client generated behind the scenes.
When doing API-First with AsyncAPI, the process is similar. After you generate some interfaces and DTOs from your API definition, you use the generated interfaces to produce messages, sending them to the broker, and implement them to consume messages from the broker.
There is still a fundamental difference between OpenAPI and AsyncAPI: OpenAPI is used to document Request-Response / Client-Server APIs, while AsyncAPI is used to document Event-Driven APIs which, with the exception of websockets, are Broker-based.
And broker-based APIs, unlike Client-Server, are inherently symmetric.
Broker-based APIs are Symmetric
Because APIs mediated by a broker are inherently symmetric it’s difficult to establish the roles of client/server: what represents a publish operation from one side will be a subscribe operation seen from the other side. Also, a given service can act as a publisher and subscriber on the same API.
For these reasons, to avoid defining the same API operations multiple times from each perspective, we propose to define the API only once from the perspective of the provider of the functionality, which may be a producer, a consumer or both.
Some definitions:
- SERVICE: An independent piece of software, typically a microservice, that provides a set of capabilities to other services.
- PROVIDER: The service that implements the functionality of the API. It may be accepting asynchronous command request or publishing business domain events.
- CLIENT/s: The service/s that makes use of the functionality of the API. It may be requesting asynchronous commands or subscribing to business domain events.
- PRODUCER: A service that writes a given message.
- CONSUMER: A service that reads a given message.
Define your AsyncAPI from the perspective of the PROVIDER of the functionality, which may be a producer, a consumer or both. Share this definition with your CLIENTS.
Use the table to understand which section of AsyncAPI (publish or subscribe) to use for each topic, and which role (provider or client) to use on the plugin configuration.
| | Events | Commands |
|------------------------------|----------------------|----------------------|
| Provider | Produces (publish) | Consumes (subscribe) |
| Client | Consumes (subscribe) | Produces (publish) |
| OperationId Suggested Prefix | **on**<Event Name> | **do**<Command Name> |If you still find confusing which one is a provider and a client just use this rule: In a given messaging scenario, there can be only one provider of a message, while there can be multiple clients.
- If the provider is the producer use publish section,
- If is the consumer use subscribe section.
Events, Commands, and Messages
In a messaging system, there are two types of messages: events and commands. An event message describes a change that has already happened, while a command message describes an operation that needs to be carried out. In other words, events are used to notify subscribers about something that has already occurred, while commands are used to initiate an action or process.
- Event: A message describing a change that has already happened.
- Command: A message describing an operation that has to be carried out.
Also, while there can be only one provider that produces a given event, but commands can be issued for one or many client producers.
Checkout ZenWave SDK: Java Generator for AsyncAPI article if you wan to learn more about how to generate those business interfaces, DTOs and header objects or keep reading if you want to learn more about API-First with AsyncAPI specification.
Understanding AsyncAPI Definition
While OpenAPI and AsyncAPI come to document completely different architectural styles, they are similar in many aspects, in fact AsyncAPI YAML format was originaly based on OpenAPI format and structure.
If you are familiar with OpenAPI you may find useful the following image borrowed from AsyncAPI documentation (click image to follow):
Info
Document your API: name, purpose, contact details, license…
Servers
Document where your API will be deployed and required security…
You can also document some server protocol specific configurations using free-form bindings property
Channels: Publish / Subscribe
Each channel represent one broker topic, channel, queue… where you are about to publish or subscribe to.
Use table above to understand which section, publish or subscribe, you may want to use.
In a nutshell:
Providers publish events and subscribe to commands/queries/requests.
If you still find confusing which one is a provider and a client just use this rule: In a given messaging scenario, there can be only one provider of a message, while there can be multiple clients. If the provider is producing messages, use the publish section. If the provider is consuming messages, use the subscribe section.
Messages
Use Messages to describe Headers, Payload Schema and Content Type. You can also include examples, descriptions and protocol-specific binding documentation…
components:
messages:
turnOnOff:
name: turnOnOff
title: Turn on/off
summary: Command a particular streetlight to turn the lights on or off.
headers:
type: object
properties:
my-app-header:
type: string
payload:
$ref: "#/components/schemas/turnOnOffPayload"Message Payloads / Schemas
You can define message payloads as:
- Inline components/schemas in the same familiar way you do in OpenAPI
- External files: both
json-schemaandavro schemas(.avsc) are supported
components:
messages:
MessageWithAsyncAPISchema:
payload:
$ref: "#/components/schemas/turnOnOffPayload" ## asyncapi/inline schema
MessageWithExternalJsonSchema:
schemaFormat: 'application/schema+json;version=draft-07'
payload:
$ref: "some/external/file.schema" ## a json-schema file
MessageWithAvroSchema:
schemaFormat: application/vnd.apache.avro+json;version=1.9.0
payload:
$ref: "v1/imports/file.avsc" ## and avro schema fileReusing Configurations: Operation Traits, Message Traits…
Operation Traits, Message Traits are an excellent way to reuse chunks of configuration between different operations or messages.
For instance if various messages share some common headers, you can configure them as Message Traits:
components:
messages:
CustomerEventMessage:
name: CustomerEventMessage
title: Async Event for a Customer
summary: Async Event for a Customer
schemaFormat: application/vnd.aai.asyncapi;version=2.4.0
traits:
- $ref: '#/components/messageTraits/CommonHeaders' # 'CommonHeaders' contents will replace 'traits' property
payload:
$ref: '#/components/schemas/CustomerEventPayload'
messageTraits:
CommonHeaders:
headers:
type: object
properties:
my-app-header:
type: integer
minimum: 0
maximum: 100And the same concept applies to Operation Traits.
Different Styles of Messages
There are three types of Event Message Styles: Notification, State Transfer and Domain Event Messages.
Notification Messages
An Event Notification contains minimal information about the event and enough information for interested consumers to locate additional details. The specifics of what information is included in an event notification can vary depending on the system or use case.
{
"headers": {
"event-type": "customer-created",
"event-id": "",
"aggregate-id": "1",
"aggregate-type": "customer"
},
"payload": {
"id": 1,
"eventType": "created",
"link": "/customers/1"
}
}State Transfer Messages
On the other hand a State Transfer message contains the entire state of the aggregate so consumer does not need to make additional calls. This can be useful in situations where subscribers need to maintain a synchronized view of the data. Compacted keyed topics typically use this style of messages.
{
"headers": {
"event-id": "",
"aggregate-id": "1",
"aggregate-type": "customer"
},
"payload": {
"id": 1,
"firstName": "string",
"lastName": "string",
"password": "string",
"email": "string",
"username": "string",
"address": {
"id": 1,
"street": "string",
"city": "string",
"state": "string",
"zip": "string"
}
}
}Domain Event Messages
Domain Event Messages contains information about the event and interesting portions of the underlying aggregate, but not the entire state of the aggregate. This style of events is typically used for Event Sourcing integration patterns.
{
"headers": {
"event-type": "customer-address-updated",
"event-id": "",
"aggregate-id": "1",
"aggregate-type": "customer"
},
"payload": {
"id": 1,
"eventType": "address-updated",
"customer": {
"id": 1,
"old-address": {
"street": "string",
"city": "string",
"state": "string",
"zip": "string"
},
"new-address": {
"street": "string",
"city": "string",
"state": "string",
"zip": "string"
}
}
}
}API-First Generator for Java and AsyncAPI
If you’re interested in learning more about how to use AsyncAPI and API-First principles in your Java projects, I invite you to check out the “API-First Generator for Java and AsyncAPI” article. In this article, you’ll learn how to use the AsyncAPI Generator and Maven Plugin to quickly generate producer and consumer code for your AsyncAPI-defined APIs.
By leveraging the power of AsyncAPI and API-First, you can reduce development time, improve code quality, and deliver more value to your customers.
Thank you for reading, and happy coding!
ZenWave360 © 2023 — Domain Driven Design and API-First for Event Driven Microservices
Originally published at https://zenwave360.github.io/