From 4e0a02df43eb4fb80c77bed1186c6c0ff24ea3f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20B=C3=BChler?= <17296905+buehlefs@users.noreply.github.com> Date: Thu, 30 Nov 2023 21:46:33 +0100 Subject: [PATCH 1/6] docs: add definition for operation (#993) --- spec/asyncapi.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 15d51f22..fbc00dc3 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -131,6 +131,9 @@ A sender is a type of application, that is sending [messages](#definitionsMessag ### Receiver A receiver is a type of application that is receiving [messages](#definitionsMessage) from [channels](#definitionsChannel). A receiver MAY receive from multiple channels depending on the [server](#definitionsServer), protocol, and the use-case pattern. A receiver MAY forward a received message further without changing it. A receiver MAY act as a consumer and react to the message. A receiver MAY act as a processor that, for example, aggregates multiple messages in one and forwards them. +### Operation +An operation describes a specific action an [application](#definitionsApplication) can take to interact with the message-driven API. Operations are performed by sending (or receiving) [messages](#definitionsMessage) to (or from) [channels](#definitionsChannel). + ### Message A message is the mechanism by which information is exchanged via a channel between [servers](#definitionsServer) and applications. A message MAY contain a payload and MAY also contain headers. The headers MAY be subdivided into [protocol](#definitionsProtocol)-defined headers and header properties defined by the application which can act as supporting metadata. The payload contains the data, defined by the application, which MUST be serialized into a format (JSON, XML, Avro, binary, etc.). Since a message is a generic mechanism, it can support multiple interaction patterns such as event, command, request, or response. From 4b0ef29a9fb2d5d38190aa9282cda73a93aec99c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20B=C3=BChler?= <17296905+buehlefs@users.noreply.github.com> Date: Thu, 30 Nov 2023 21:55:29 +0100 Subject: [PATCH 2/6] docs: add links to operation definition --- spec/asyncapi.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index fbc00dc3..0369e3df 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -17,7 +17,7 @@ The AsyncAPI Specification is a project used to describe message-driven APIs in The AsyncAPI Specification defines a set of files required to describe the API of an [application](#definitionsApplication). These files can be used to create utilities, such as documentation, code, integration, or testing tools. -The file(s) SHOULD describe the operations an [application](#definitionsApplication) performs. For instance, consider the following AsyncAPI definition snippet: +The file(s) SHOULD describe the [operations](#definitionsOperation) an [application](#definitionsApplication) performs. For instance, consider the following AsyncAPI definition snippet: ```yaml channels: @@ -34,7 +34,7 @@ It means that the [application](#definitionsApplication) will receive messages f **The AsyncAPI specification does not assume any kind of software topology, architecture or pattern.** Therefore, a server MAY be a message broker, a web server or any other kind of computer program capable of sending and/or receiving data. However, AsyncAPI offers a mechanism called "bindings" that aims to help with more specific information about the protocol. -It's NOT RECOMMENDED to derive a [receiver](#definitionsReceiver) AsyncAPI document from a [sender](#definitionsSender) one or vice versa. There are no guarantees that the channel used by an application to receive messages will be the same channel where another application is sending them. Also, certain fields in the document like `summary`, `description`, and the id of the operation might stop making sense. For instance, given the following receiver snippet: +It's NOT RECOMMENDED to derive a [receiver](#definitionsReceiver) AsyncAPI document from a [sender](#definitionsSender) one or vice versa. There are no guarantees that the channel used by an application to receive messages will be the same channel where another application is sending them. Also, certain fields in the document like `summary`, `description`, and the id of the [operation](#definitionsOperation) might stop making sense. For instance, given the following receiver snippet: ```yaml operations: @@ -138,7 +138,7 @@ An operation describes a specific action an [application](#definitionsApplicatio A message is the mechanism by which information is exchanged via a channel between [servers](#definitionsServer) and applications. A message MAY contain a payload and MAY also contain headers. The headers MAY be subdivided into [protocol](#definitionsProtocol)-defined headers and header properties defined by the application which can act as supporting metadata. The payload contains the data, defined by the application, which MUST be serialized into a format (JSON, XML, Avro, binary, etc.). Since a message is a generic mechanism, it can support multiple interaction patterns such as event, command, request, or response. ### Channel -A channel is an addressable component, made available by the [server](#definitionsServer), for the organization of [messages](#definitionsMessage). [Sender](#definitionsSender) applications send messages to channels and [receiver](#definitionsReceiver) applications receive messages from channels. [Servers](#definitionsServer) MAY support many channel instances, allowing messages with different content to be addressed to different channels. Depending on the [server](#definitionsServer) implementation, the channel MAY be included in the message via protocol-defined headers. +A channel is an addressable component, made available by the [server](#definitionsServer), for the organization of [messages](#definitionsMessage). [Sender](#definitionsSender) applications send messages to channels and [receiver](#definitionsReceiver) applications receive messages from channels to perform an [operation](#definitionsOperation). [Servers](#definitionsServer) MAY support many channel instances, allowing messages with different content to be addressed to different channels. Depending on the [server](#definitionsServer) implementation, the channel MAY be included in the message via protocol-defined headers. ### Protocol A protocol is the mechanism (wireline protocol or API) by which [messages](#definitionsMessage) are exchanged between the application and the [channel](#definitionsChannel). Example protocols include, but are not limited to, AMQP, HTTP, JMS, Kafka, Anypoint MQ, MQTT, Solace, STOMP, Mercure, WebSocket, Google Pub/Sub, Pulsar. @@ -204,7 +204,7 @@ Field Name | Type | Description servers | [Servers Object](#serversObject) | Provides connection details of servers. defaultContentType | [Default Content Type](#defaultContentTypeString) | Default content type to use when encoding/decoding a message's payload. channels | [Channels Object](#channelsObject) | The channels used by this [application](#definitionsApplication). -operations | [Operations Object](#operationsObject) | The operations this [application](#definitionsApplication) MUST implement. +operations | [Operations Object](#operationsObject) | The [operations](#definitionsOperation) this [application](#definitionsApplication) MUST implement. components | [Components Object](#componentsObject) | An element to hold various reusable objects for the specification. Everything that is defined inside this object represents a resource that MAY or MAY NOT be used in the rest of the document and MAY or MAY NOT be used by the implemented [Application](#definitionsApplication). This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -469,7 +469,7 @@ Field Name | Type | Description title | `string` | A human-friendly title for the server. summary | `string` | A short summary of the server. variables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)]] | A map between a variable name and its value. The value is used for substitution in the server's `host` and `pathname` template. -security | [[Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | A declaration of which security schemes can be used with this server. The list of values includes alternative [security scheme objects](#securitySchemeObject) that can be used. Only one of the security scheme objects need to be satisfied to authorize a connection or operation. +security | [[Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | A declaration of which security schemes can be used with this server. The list of values includes alternative [security scheme objects](#securitySchemeObject) that can be used. Only one of the security scheme objects need to be satisfied to authorize a connection or [operation](#definitionsOperation). tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of servers. externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this server. bindings | [Server Bindings Object](#serverBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the server. @@ -769,7 +769,7 @@ Holds a dictionary with all the [operations](#operationObject) this application Field Pattern | Type | Description ---|:---:|--- -{operationId} | [Operation Object](#operationObject) \| [Reference Object](#referenceObject) | The operation this application MUST implement. The field name (`operationId`) MUST be a string used to identify the operation in the document where it is defined, and its value is **case-sensitive**. Tools and libraries MAY use the `operationId` to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. +{operationId} | [Operation Object](#operationObject) \| [Reference Object](#referenceObject) | The [operation](#definitionsOperation) this application MUST implement. The field name (`operationId`) MUST be a string used to identify the operation in the document where it is defined, and its value is **case-sensitive**. Tools and libraries MAY use the `operationId` to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. ##### Operations Object Example @@ -822,7 +822,7 @@ onUserSignUp: #### Operation Object -Describes a specific operation. +Describes a specific [operation](#definitionsOperation). ##### Fixed Fields @@ -969,7 +969,7 @@ bindings: #### Operation Reply Object -Describes the reply part that MAY be applied to an Operation Object. If an operation implements the request/reply pattern, the reply object represents the response message. +Describes the reply part that MAY be applied to an Operation Object. If an [operation](#definitionsOperation) implements the request/reply pattern, the reply object represents the response message. ##### Fixed Fields @@ -983,7 +983,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens #### Operation Reply Address Object -An object that specifies where an operation has to send the reply. +An object that specifies where an [operation](#definitionsOperation) has to send the reply. For specifying and computing the location of a reply address, a [runtime expression](#runtimeExpression) is used. From 9bf317d47eb252818f34a9fffd2fd0b25bad2ca7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20B=C3=BChler?= <17296905+buehlefs@users.noreply.github.com> Date: Thu, 30 Nov 2023 21:59:11 +0100 Subject: [PATCH 3/6] docs: reword message object description to align with new operation definition --- spec/asyncapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 0369e3df..7841c284 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -1224,7 +1224,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens #### Message Object -Describes a message received on a given channel and operation. +Describes a [message](#definitionsMessage) that can be sent to or received from a given [channel](#definitionsChannel) to perform an [operation](#definitionsOperation). ##### Fixed Fields From c36274fdbd78d9c13ecbc96f5921410cd65b3285 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20B=C3=BChler?= <17296905+buehlefs@users.noreply.github.com> Date: Wed, 10 Apr 2024 22:23:33 +0200 Subject: [PATCH 4/6] docs: add toc entry for operation definition --- spec/asyncapi.md | 1 + 1 file changed, 1 insertion(+) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 7841c284..6fa67cec 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -68,6 +68,7 @@ Aside from the issues mentioned above, there may also be infrastructure configur - [Application](#definitionsApplication) - [Sender](#definitionsSender) - [Receiver](#definitionsReceiver) + - [Operation](#definitionsOperation) - [Message](#definitionsMessage) - [Channel](#definitionsChannel) - [Protocol](#definitionsProtocol) From 6caa3e844796fbf009e30583b0e3cb6725f73fb0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20B=C3=BChler?= <17296905+buehlefs@users.noreply.github.com> Date: Wed, 10 Apr 2024 22:24:23 +0200 Subject: [PATCH 5/6] docs: reword operation definition --- spec/asyncapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 6fa67cec..47964810 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -133,7 +133,7 @@ A sender is a type of application, that is sending [messages](#definitionsMessag A receiver is a type of application that is receiving [messages](#definitionsMessage) from [channels](#definitionsChannel). A receiver MAY receive from multiple channels depending on the [server](#definitionsServer), protocol, and the use-case pattern. A receiver MAY forward a received message further without changing it. A receiver MAY act as a consumer and react to the message. A receiver MAY act as a processor that, for example, aggregates multiple messages in one and forwards them. ### Operation -An operation describes a specific action an [application](#definitionsApplication) can take to interact with the message-driven API. Operations are performed by sending (or receiving) [messages](#definitionsMessage) to (or from) [channels](#definitionsChannel). +An operation describes a specific action an [application](#definitionsApplication) can take to interact with other [sender](#definitionsSender) or [receiver](#definitionsReceiver) applications. Operations are performed by sending (or receiving) [messages](#definitionsMessage) to (or from) [channels](#definitionsChannel). ### Message A message is the mechanism by which information is exchanged via a channel between [servers](#definitionsServer) and applications. A message MAY contain a payload and MAY also contain headers. The headers MAY be subdivided into [protocol](#definitionsProtocol)-defined headers and header properties defined by the application which can act as supporting metadata. The payload contains the data, defined by the application, which MUST be serialized into a format (JSON, XML, Avro, binary, etc.). Since a message is a generic mechanism, it can support multiple interaction patterns such as event, command, request, or response. From ecb3a89fe1136c77bccc6973f10791f9715457d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20B=C3=BChler?= <17296905+buehlefs@users.noreply.github.com> Date: Wed, 24 Apr 2024 12:30:29 +0200 Subject: [PATCH 6/6] Fix missing newline --- spec/asyncapi.md | 1 + 1 file changed, 1 insertion(+) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 3e26f0c5..95f5ef99 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -136,6 +136,7 @@ A sender is a type of application, that is sending [messages](#definitionsMessag A receiver is a type of application that is receiving [messages](#definitionsMessage) from [channels](#definitionsChannel). A receiver MAY receive from multiple channels depending on the [server](#definitionsServer), protocol, and the use-case pattern. A receiver MAY forward a received message further without changing it. A receiver MAY act as a consumer and react to the message. A receiver MAY act as a processor that, for example, aggregates multiple messages in one and forwards them. ### Operation + An operation describes a specific action an [application](#definitionsApplication) can take to interact with other [sender](#definitionsSender) or [receiver](#definitionsReceiver) applications. Operations are performed by sending (or receiving) [messages](#definitionsMessage) to (or from) [channels](#definitionsChannel). ### Message