From 36061cdba277d525e19ec00e2faa896b9f189c6b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=20M=C3=A9ndez?= Date: Tue, 17 Jan 2023 16:35:16 +0100 Subject: [PATCH 1/2] feat: unify all referencing mechanisms (#852) --- spec/asyncapi.md | 277 ++++++++++++++--------------------------------- 1 file changed, 81 insertions(+), 196 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index f75cd7848..b3f0a35e6 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -75,7 +75,6 @@ It means that the [application](#definitionsApplication) allows [consumers](#def - [Reference Object](#referenceObject) - [Schema Object](#schemaObject) - [Security Scheme Object](#securitySchemeObject) - - [Security Requirement Object](#security-requirement-object) - [OAuth Flows Object](#oauth-flows-object) - [OAuth Flow Object](#oauth-flow-object) - [Server Bindings Object](#serverBindingsObject) @@ -406,7 +405,7 @@ Field Name | Type | Description summary | `string` | A short summary of the server. description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. 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 URL template. -security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used with this server. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement 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. 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. @@ -449,128 +448,82 @@ externalDocs: url: https://kafka.apache.org/ ``` -The following shows how multiple servers can be described, for example, at the AsyncAPI Object's [`servers`](#A2SServers): +Using server variables for dynamic URLs: ```json { - "servers": { - "development": { - "url": "development.gigantic-server.com", - "protocol": "amqp", - "protocolVersion": "0.9.1", - "title": "Development server", - "tags": [ - { - "name": "env:development", - "description": "This environment is meant for developers to run their own tests" - } - ] + "url": "{username}.gigantic-server.com:{port}/{basePath}", + "description": "The production API server", + "protocol": "secure-mqtt", + "variables": { + "username": { + "default": "demo", + "description": "This value is assigned by the service provider, in this example `gigantic-server.com`" }, - "staging": { - "url": "staging.gigantic-server.com", - "protocol": "amqp", - "protocolVersion": "0.9.1", - "title": "Staging server", - "tags": [ - { - "name": "env:staging", - "description": "This environment is a replica of the production environment" - } - ] + "port": { + "enum": [ + "8883", + "8884" + ], + "default": "8883" }, - "production": { - "url": "api.gigantic-server.com", - "protocol": "amqp", - "protocolVersion": "0.9.1", - "title": "Production server", - "tags": [ - { - "name": "env:production", - "description": "This environment is the live environment available for final users" - } - ] + "basePath": { + "default": "v2" } } } ``` ```yaml -servers: - development: - url: development.gigantic-server.com - protocol: amqp - protocolVersion: 0.9.1 - title: Development server - tags: - - name: "env:development" - description: "This environment is meant for developers to run their own tests" - staging: - url: staging.gigantic-server.com - protocol: amqp - protocolVersion: 0.9.1 - title: Staging server - tags: - - name: "env:staging" - description: "This environment is a replica of the production environment" - production: - url: api.gigantic-server.com - protocol: amqp - protocolVersion: 0.9.1 - title: Production server - tags: - - name: "env:production" - description: "This environment is the live environment available for final users" -``` - -The following shows how variables can be used for a server configuration: +url: '{username}.gigantic-server.com:{port}/{basePath}' +description: The production API server +protocol: secure-mqtt +variables: + username: + # Note: no enum here means it is an open value. + default: demo + description: This value is assigned by the service provider, in this example `gigantic-server.com` + port: + enum: + - '8883' + - '8884' + default: '8883' + basePath: + # Note: open meaning. There is the opportunity to use special base paths as assigned by the provider, default is `v2`. + default: v2 +``` + +Using security mechanisms: ```json { - "servers": { - "production": { - "url": "{username}.gigantic-server.com:{port}/{basePath}", - "protocol": "secure-mqtt", - "title": "Production server", - "variables": { - "username": { - "default": "demo", - "description": "This value is assigned by the service provider, in this example `gigantic-server.com`" - }, - "port": { - "enum": [ - "8883", - "8884" - ], - "default": "8883" - }, - "basePath": { - "default": "v2" - } - } + "url": "broker.company.com", + "description": "Production MQTT broker", + "protocol": "secure-mqtt", + "protocolVersion": "5", + "security": [ + { + "type": "userPassword", + "description": "Connect to the MQTT broker using basic authentication." + }, + { + "type": "X509", + "description": "Connect to the MQTT broker using a X509 certificate." } - } + ] } ``` ```yaml -servers: - production: - url: '{username}.gigantic-server.com:{port}/{basePath}' - protocol: secure-mqtt - title: Production server - variables: - username: - # note! no enum here means it is an open value - default: demo - description: This value is assigned by the service provider, in this example `gigantic-server.com` - port: - enum: - - '8883' - - '8884' - default: '8883' - basePath: - # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2` - default: v2 +url: broker.company.com +description: Production MQTT broker +protocol: secure-mqtt +protocolVersion: '5' +security: + - type: userPassword + description: Connect to the MQTT broker using basic authentication. + - type: X509 + description: Connect to the MQTT broker using a X509 certificate. ``` @@ -864,8 +817,8 @@ Field Name | Type | Description channel | [Reference Object](#referenceObject) | **Required**. A `$ref` pointer to the definition of the channel in which this operation is performed. Please note the `channel` property value MUST be a [Reference Object](#referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channelObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. title | `string` | A human-friendly title for the operation. summary | `string` | A short summary of what the operation is about. -description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -security | [[Security Requirement Object](#securityRequirementObject)]| A declaration of which security mechanisms are associated with this operation. Only one of the security requirement objects MUST be satisfied to authorize an operation. In cases where Server Security also applies, it MUST also be satisfied. +description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. +security | [[Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)]| A declaration of which security schemes are associated with this operation. Only one of the [security scheme objects](#securitySchemeObject) MUST be satisfied to authorize an operation. In cases where [Server Security](#serverObjectSecurity) also applies, it MUST also be satisfied. tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of operations. externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this operation. bindings | [Operation Bindings Object](#operationBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. @@ -946,7 +899,7 @@ Field Name | Type | Description title | `string` | A human-friendly title for the operation. summary | `string` | A short summary of what the operation is about. description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -security | [[Security Requirement Object](#securityRequirementObject)]| A declaration of which security mechanisms are associated with this operation. Only one of the security requirement objects MUST be satisfied to authorize an operation. In cases where Server Security also applies, it MUST also be satisfied. +security | [[Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)]| A declaration of which security schemes are associated with this operation. Only one of the [security scheme objects](#securitySchemeObject) MUST be satisfied to authorize an operation. In cases where [Server Security](#serverObjectSecurity) also applies, it MUST also be satisfied. tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of operations. externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this operation. bindings | [Operation Bindings Object](#operationBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. @@ -2335,6 +2288,7 @@ Field Name | Type | Applies To | Description bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported. openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of an absolute URL. +scopes | [`string`] | `oauth2` \| `openIdConnect` | List of the needed scope names. An empty array means no scopes are needed. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -2444,12 +2398,15 @@ bearerFormat: JWT "flows": { "implicit": { "authorizationUrl": "https://example.com/api/oauth/dialog", - "scopes": { + "availableScopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } } - } + }, + "scopes": [ + "write:pets" + ] } ``` @@ -2458,9 +2415,11 @@ type: oauth2 flows: implicit: authorizationUrl: https://example.com/api/oauth/dialog - scopes: + availableScopes: write:pets: modify pets in your account read:pets: read your pets +scopes: + - 'write:pets' ``` ###### SASL Sample @@ -2499,7 +2458,7 @@ Field Name | Type | Applies To | Description authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of an absolute URL. tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of an absolute URL. refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL. -scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. +availableScopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -2507,98 +2466,24 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ```JSON { - "type": "oauth2", - "flows": { - "implicit": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - }, - "authorizationCode": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "tokenUrl": "https://example.com/api/oauth/token", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - } + "authorizationUrl": "https://example.com/api/oauth/dialog", + "tokenUrl": "https://example.com/api/oauth/token", + "availableScopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" } } ``` ```YAML -type: oauth2 -flows: - implicit: - authorizationUrl: https://example.com/api/oauth/dialog - scopes: - write:pets: modify pets in your account - read:pets: read your pets - authorizationCode: - authorizationUrl: https://example.com/api/oauth/dialog - tokenUrl: https://example.com/api/oauth/token - scopes: - write:pets: modify pets in your account - read:pets: read your pets -``` - -#### Security Requirement Object - -Lists the required security schemes to execute this operation. -The name used for each property MUST correspond to a security scheme declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). - -When a list of Security Requirement Objects is defined on a [Server object](#serverObject), only one of the Security Requirement Objects in the list needs to be satisfied to authorize the connection. - -##### Patterned Fields - -Field Pattern | Type | Description ----|:---:|--- -{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names. Provide scopes that are required to establish successful connection with the server. If scopes are not needed, the list can be empty. For other security scheme types, the array MUST be empty. - -##### Security Requirement Object Examples - -###### User/Password Security Requirement - -```json -{ - "user_pass": [] -} +authorizationUrl: https://example.com/api/oauth/dialog +tokenUrl: https://example.com/api/oauth/token +availableScopes: + write:pets: modify pets in your account + read:pets: read your pets ``` -```yaml -user_pass: [] -``` - -###### API Key Security Requirement - -```json -{ - "api_key": [] -} -``` - -```yaml -api_key: [] -``` - -###### OAuth2 Security Requirement - -```json -{ - "petstore_auth": [ - "write:pets", - "read:pets" - ] -} -``` -```yaml -petstore_auth: -- write:pets -- read:pets -``` ### Correlation ID Object From df2bab7c833075a45ad31d310b3321da718d8a8e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=20M=C3=A9ndez?= Date: Sun, 22 Jan 2023 19:37:07 +0100 Subject: [PATCH 2/2] chore: clarify introduction (#875) --- spec/asyncapi.md | 48 +++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 39 insertions(+), 9 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index b3f0a35e6..4c363e227 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -16,24 +16,54 @@ The AsyncAPI Specification is licensed under [The Apache License, Version 2.0](h ## Introduction -The AsyncAPI Specification is a project used to describe and document message-driven APIs in a machine-readable format. It’s protocol-agnostic, so you can use it for APIs that work over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, STOMP, HTTP, Mercure, etc). +The AsyncAPI Specification is a project used to describe message-driven APIs in a machine-readable format. It’s protocol-agnostic, so you can use it for APIs that work over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, STOMP, HTTP, Mercure, etc). -The AsyncAPI Specification defines a set of files required to describe such an API. -These files can then be used to create utilities, such as documentation, integration and/or testing tools. +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) MUST describe the operations an [application](#definitionsApplication) accepts. For instance, consider the following AsyncAPI definition snippet: +The file(s) MUST describe the operations an [application](#definitionsApplication) performs. For instance, consider the following AsyncAPI definition snippet: ```yaml -user/signedup: - subscribe: - message: - $ref: "#/components/messages/userSignUp" +channels: + userSignedUp: + # ...(redacted for brevity) +operations: + onUserSignedUp: + action: receive + channel: + $ref: "#/channels/userSignedUp" ``` -It means that the [application](#definitionsApplication) allows [consumers](#definitionsConsumer) to subscribe to the `user/signedup` [channel](#definitionsChannel) to receive userSignUp [messages](#definitionsMessage) produced by the application. +It means that the [application](#definitionsApplication) will subscribe to the `userSignedUp` [channel](#definitionsChannel) to receive messages. **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 [consumer](#definitionsConsumer) AsyncAPI document from a [producer](#definitionsProducer) 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 consumer snippet: + +```yaml +operations: + onUserSignedUp: + summary: On user signed up. + description: Event received when a user signed up on the product. + action: receive + channel: + $ref: "#/channels/userSignedUp" +``` + +We can't automatically assume that an _opposite_ application exists by simply replacing `receive` with `send`: + +```yaml +operations: + onUserSignedUp: # <-- This doesn't make sense now. Should be something like sendUserSignedUp. + summary: On user signed up. # <-- This doesn't make sense now. Should say something like "Sends a user signed up event". + description: Event received when a user signed up on the product. # <-- This doesn't make sense now. Should speak about sending an event, not receiving it. + action: send + channel: + $ref: "#/channels/userSignedUp" +``` + +Aside from the issues mentioned above, there may also be infrastructure configuration that is not represented here. For instance, a system may use a read-only channel for receiving messages, a different one for sending them, and an intermediary process that will forward messages from one channel to the other. + ## Table of Contents