asyncapi-design

# AsyncAPI Design Skill

## When to Use This Skill

Use this skill when:

- **Designing event-driven APIs** - AsyncAPI 3.0 for message-based architectures
- **Configuring message brokers** - Kafka, RabbitMQ, MQTT, WebSocket bindings
- **Implementing in C#** - Event contracts, MassTransit, Confluent Kafka
- **Event versioning** - Schema evolution and backward compatibility

## MANDATORY: Documentation-First Approach

Before creating AsyncAPI specifications:

1. **Invoke `docs-management` skill** for event-driven patterns
2. **Verify AsyncAPI 3.0 syntax** via MCP servers (context7 for latest spec)
3. **Base all guidance on AsyncAPI 3.0 specification**

## AsyncAPI vs OpenAPI

| Aspect | OpenAPI | AsyncAPI |
|--------|---------|----------|
| Communication | Request/Response | Event-Driven |
| Protocol | HTTP/HTTPS | Kafka, RabbitMQ, MQTT, WebSocket |
| Initiator | Client requests | Publisher emits |
| Pattern | Synchronous | Asynchronous |
| Use Case | REST APIs | Message queues, streaming, IoT |

## AsyncAPI 3.0 Structure Overview

```yaml
asyncapi: 3.0.0
info:
  title: API Title
  version: 1.0.0

servers:
  production:
    host: kafka.example.com:9092
    protocol: kafka

channels:
  orderCreated:
    address: orders.created
    messages:
      orderCreatedMessage:
        $ref: '#/components/messages/OrderCreated'

operations:
  publishOrderCreated:
    action: send
    channel:
      $ref: '#/channels/orderCreated'

components:
  messages: { }
  schemas: { }
  securitySchemes: { }
```

**For complete template**: See [basic-template.md](references/basic-template.md)

## Quick Reference

### Supported Protocols

| Protocol | Use Case | Binding Version |
|----------|----------|-----------------|
| Kafka | High-throughput streaming | 0.5.0 |
| AMQP (RabbitMQ) | Message queuing | 0.3.0 |
| MQTT | IoT, lightweight messaging | 0.2.0 |
| WebSocket | Real-time browser comms | - |

**For protocol-specific patterns**: See [protocol-patterns.md](references/protocol-patterns.md