Channels and Operations
Define channels (topics, queues, subjects) and operations (send/receive) for async event APIs. Configure addresses with parameters, protocol bindings, and request-reply patterns.
Channels and operations are the core building blocks of async API documentation. A channel represents a message destination (topic, queue, or subject) while an operation describes how your application interacts with that channel.
Channels
A channel represents a destination where messages are sent and received. Depending on the protocol, this maps to a Kafka topic, AMQP exchange/queue, MQTT topic, or other protocol-specific concept.
| Property | Description |
|---|---|
| Name | Human-readable name for the channel |
| Address | The channel address or topic pattern (e.g. orders.{orderId}.events) |
| Parameters | Dynamic address segments auto-detected from {expression} tokens |
| Messages | References to messages that can appear on this channel |
| Server Refs | Which servers this channel is available on |
| Protocol Bindings | Protocol-specific configuration (partitions, retention, QoS, etc.) |
| Tags | Categorisation tags for filtering and organisation |
Address Parameters
When you include {parameter} expressions in a channel address, NeoArc automatically detects and creates parameter entries. Each parameter can have a description, enum values, and examples.
Example: Order Events Channel
Operations
An operation describes how your application interacts with a channel. The two actions are send (your application publishes messages) and receive (your application subscribes to messages).
| Property | Description |
|---|---|
| Name | Operation identifier (e.g. publishOrderCreated) |
| Action | send (publish) or receive (subscribe) from the application's perspective |
| Channel Ref | The channel this operation acts on |
| Messages | References to the messages this operation sends or receives |
| Security | Per-operation security requirements (overrides API default) |
| Reply | Optional request-reply configuration with reply channel and messages |
| Protocol Bindings | Kafka consumer group, AMQP delivery mode, MQTT QoS, etc. |
| Traits | Reusable operation traits for cross-cutting concerns |
| Deprecated | Mark operations as deprecated with migration guidance |
Send vs Receive
Example: Send Operation
Example: Receive Operation
Request-Reply Pattern
Operations can define a reply configuration for request-reply messaging patterns. Specify a reply channel, reply messages, and an address location expression for dynamic reply destinations.
| Reply Property | Description |
|---|---|
| Channel Ref | The channel where replies are expected |
| Message Refs | Messages that constitute valid replies |
| Address Location | Runtime expression for the reply address (e.g. $message.header#/replyTo) |
| Description | Human-readable description of the reply mechanism |
Operation Traits
Operation traits capture reusable cross-cutting properties that apply to multiple operations. Common use cases include shared security requirements, standard bindings, and tagging conventions. Traits are defined in the API definition and referenced by operations.