| name | mendez-async-api |
| description | Design event-driven architectures using Fran Méndez's "AsyncAPI" philosophy. Emphasizes Event-First design, treating message contracts with the same rigor as REST (AsyncAPI spec), and decoupling producers from consumers. Use when building message buses, IoT networks, or microservices that communicate asynchronously. |
| tags | async-api, event-driven, message-broker, pubsub, kafka, rabbitmq, websocket, streaming, microservices, mqtt |
Fran Méndez Style Guide
Overview
Fran Méndez (Creator of AsyncAPI) champions the Event-First approach. Just as OpenAPI standardized REST, AsyncAPI standardizes message-driven systems. His philosophy ensures that asynchronous systems are documented, readable, and machine-enforceable, moving away from "hidden knowledge" in code to explicit contracts.
"Events are as important as your HTTP requests. Document them, govern them, and design them first."
Core Principles
- Event First: Define the AsyncAPI specification before implementing publishers or subscribers. The spec is the architecture.
- Channel-Centric Design: Focus on the channels (topics/queues) and the messages that flow through them, not just the services.
- Protocol Agnostic: Your design should describe the application, whether it runs on Kafka, MQTT, RabbitMQ, or WebSockets.
- Schema Governance: Reuse schemas (payloads) across different messages to ensure data consistency.
- Documentation as Infrastructure: Your AsyncAPI file isn't just docs; it's the config for your code generators, validators, and mocks.
Prompts
Design an Event-Driven System
"Act as Fran Méndez. Design an event-driven architecture for [System]. Start by creating a comprehensive AsyncAPI 3.0 definition.
Focus on:
- Channels: Logical naming (e.g.,
user/signedup, NOT user-signedup-queue-prod).
- Messages: Define headers (metadata) and payloads separately.
- Traits: Use operation traits for common bindings (e.g., Kafka partion keys).
- Decoupling: Ensure the design promotes loose coupling between services."
Audit an Existing Messaging System
"Review this event structure from the perspective of the AsyncAPI creator.
Look for:
- Implicit Schemas: JSON payloads defined only in code/strings.
- Tight Coupling: Message structures that leak implementation details of the producer.
- Missing Metadata: Events lacking correlation IDs or timestamps in headers.
- Ambiguous Channels: Unclear topic hierarchies that make routing difficult."
Examples
The AsyncAPI Contract (The Source of Truth)
asyncapi: '3.0.0'
info:
title: Rider App Geo-Tracking
version: '1.0.0'
description: |
Handles real-time location updates from riders.
Essential for matching riders with drivers and calculating ETAs.
contact:
name: Platform Engineering
email: platform@riderapp.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
channels:
riderById:
address: 'riders/{riderId}/location'
messages:
riderLocation:
$ref: '#/components/messages/LocationUpdate'
parameters:
riderId:
description: The unique ID of the rider (UUID).
description: Stream of location updates for a specific rider.
operations:
receiveLocation:
action:
[, ]
Anti-Patterns (What NOT to do)
- Code-First Events: Using a generic
Map<String, Object> in Java or interface{} in Go and serializing it. No one knows what's in the message.
- The "God Event": One giant message on a
global-events topic that contains every possible field for every possible action.
- Ignoring Headers: Putting metadata (like
event_time or trace_id) inside the payload body instead of protocol headers.
- Protocol Coupling: Hardcoding RabbitMQ exchange names directly into the application logic instead of abstracting them via the spec.
Resources
