Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add intent-driven API v1.0.0-alpha documentation (#1)
- Loading branch information
Showing
2 changed files
with
376 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,2 +1,50 @@ | ||
| # parser-api | ||
| Global API definition for all AsyncAPI Parser implementations. | ||
|
|
||
| The API follows an Intent-driven design approach, based on user intents rather than technical mechanics. | ||
|
|
||
| An **Intent** represents a user intention of performing an action that solves a clear use case. | ||
|
|
||
| For example, `Buy five watermelons` is the intent for `Going to the fruit shop, grab five watermelons, go to the counter, pay with cash, put the watermelon in a bag, exit the shop`. | ||
|
|
||
| Based on this principle, we have built an API based on the intents of the end-users, hiding the complexity of the tasks (do not care about going to the fruit shop, we do that for you) and providing better usability. | ||
| We tried to cover most use cases; however, we cannot think of every use case, so if you feel like the API is missing an intent, please create a feature request with it. | ||
|
|
||
| Find all Parser API versions and definitions [here](docs). | ||
|
|
||
| ## Design | ||
|
|
||
| Intents are wrapped in models. Models are spec-independent but based on AsyncAPI concepts that will always exist regardless of the specification version. | ||
|
|
||
| The upsides of using this approach are: | ||
| - Better user experience. Intents are much simple to use and do not force users to know about all spec internals. | ||
| - Improves resiliency to breaking changes on the final user code. Most of the time, users will **only** need to upgrade to the latest version of the parser to be up-to-date with the latest spec. | ||
|
|
||
| All individual parsers are following the intent API. Even though that the individual parsers maintain an individual release cycle, changes to the intent API will force the individual parsers to update as well. | ||
| > Say we release a new spec version and we are forced to create a breaking change and force a major version change for the intent API (say from version 2 -> 3) the individual parsers are then forced to make a major version change as well (say JS parser go from version 1 -> 2). | ||
| Each parser will therefore maintain its own compatibility matrix between which specification and intent API versions are supported in which parser version. | ||
|
|
||
| ### Models | ||
|
|
||
| These are the models in the intent API: | ||
| - **AsyncAPI** is the root model. Most of the intents are here, so users don't need to navigate through the object hierarchy. | ||
| - **Channel** describes a `topic`/`channel` a Message is transmitted over by some Operation. | ||
| - **Contact** contains Contact information of the Application or Client API. | ||
| - **Correlation Id** specifies an identifier at design time that can used for message tracing and correlation. | ||
| - **Info** contains defined information about the Application or Client API. | ||
| - **License** contains License information of the Application or Client API. | ||
| - **Message** represents a message in your message-driven architecture. They can relate to Operations and Channels, but the relationship is not mandatory. | ||
| - **OauthFlow** holds configuration details for a supported OAuth Flow. | ||
| - **OauthFlows** allows configuration of the supported OAuth Flows. | ||
| - **Operation** describes an action performed by the Application or the Client. It links messages with channels. | ||
| - **Schema** is a superset of the [JSON Schema Specification Draft 07](https://json-schema.org/understanding-json-schema/basics.html). See https://www.asyncapi.com/docs/specifications/2.0.0#schemaObject. | ||
| - **SecurityScheme** represents security specifications for servers. | ||
| - **Server** represents a Server in your message-driven architecture. Application or Client always want to connect to some server. | ||
| - **ServerVariable** represents a Server Variable for server URL template substitution. | ||
| - **Tag** contains metadata. | ||
|
|
||
| ## Development | ||
| To avoid polluting the API with intents that have no apparent use case or can be replaced by a call to another model, we have defined the following rule: | ||
|
|
||
| Intents at the root model (`AsyncAPI`) **SHOULD** never return properties of other models but instead answer questions, return the model itself or a collection of models. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,328 @@ | ||
| # AsyncAPI Parser API v1.0.0-alpha | ||
| ## AsyncAPIDocument | ||
| - applicationPublishableChannels() : `Channel[]` | ||
| - applicationPublishableMessages() : `Message[]` | ||
| - applicationPublishOperations() : `Operation[]` | ||
| - applicationSubscribableChannels() : `Channel[]` | ||
| - applicationSubscribableMessages() : `Message[]` | ||
| - applicationSubscribeOperations() : `Operation[]` | ||
| - channels() : `Channel[]` | ||
| - clientPublishableChannels() : `Channel[]` | ||
| - clientPublishableMessages() : `Message[]` | ||
| - clientPublishOperations() : `Operation[]` | ||
| - clientSubscribableChannels() : `Channel[]` | ||
| - clientSubscribableMessages() : `Message[]` | ||
| - clientSubscribeOperations() : `Operation[]` | ||
| - defaultContentType() : `string` | `undefined` | ||
| - extension(name) : `any` | `undefined` | ||
| - name : `string` | ||
| - hasChannels() : `boolean` | ||
| - hasDefaultContentType() : `boolean` | ||
| - hasExtension(name) : `boolean` | ||
| - name : `string` | ||
| - hasServers() : `boolean` | ||
| - info() : `Info` | ||
| - messages() : `Message[]` | ||
| - operations() : `Operation[]` | ||
| - schemas() : `Schema[]` | ||
| - securitySchemes() : `SecurityScheme[]` | ||
| - server(server_name) : `Server` | `undefined` | ||
| - server_name : `string` | ||
| - servers() : `Server[]` | ||
| - version() : `string` | ||
|
|
||
| ## Channel | ||
| - binding(bindingProtocol) : `any` | `undefined` | ||
| - bindingProtocol : `enum{'amqp', 'amqps', 'http', 'https', 'jms', 'kafka', 'kafka-secure', 'mqtt', 'secure-mqtt', 'stomp', 'stomps', 'ws', 'wss'}` | ||
| - description() : `string` | `undefined` | ||
| - extension(name) : `any` | `undefined` | ||
| - name : `string` | ||
| - hasBinding(bindingProtocol) : `boolean` | ||
| - bindingProtocol : `enum{'amqp', 'amqps', 'http', 'https', 'jms', 'kafka', 'kafka-secure', 'mqtt', 'secure-mqtt', 'stomp', 'stomps', 'ws', 'wss'}` | ||
| - hasDescription() : `boolean` | ||
| - hasExtension(name) : `boolean` | ||
| - name : `string` | ||
| - hasParameters() : `boolean` | ||
| - messages() : `Message[]` | ||
| - operations() : `Operation[]` | ||
| - parameters() : `ChannelParameter[]` | ||
| - path() : `string` | ||
|
|
||
| ## ChannelParameter | ||
| - description() : `string` | `undefined` | ||
| - extension(name) : `any` | `undefined` | ||
| - name : `string` | ||
| - hasExtension(name) : `boolean` | ||
| - name : `string` | ||
| - name() : `string` | ||
| - schema() : `Schema` | ||
|
|
||
| ## Contact | ||
| - email() : `string` | `undefined` | ||
| - extension(name) : `any` | `undefined` | ||
| - name : `string` | ||
| - hasEmail() : `boolean` | ||
| - hasExtension(name) : `boolean` | ||
| - name : `string` | ||
| - hasName() : `boolean` | ||
| - hasUrl() : `boolean` | ||
| - name() : `string` | `undefined` | ||
| - url() : `string` | `undefined` | ||
|
|
||
| ## CorrelationId | ||
| - description() : `string` | `undefined` | ||
| - extension(name) : `any` | `undefined` | ||
| - name : `string` | ||
| - hasDescription() : `boolean` | ||
| - hasExtension(name) : `boolean` | ||
| - name : `string` | ||
| - hasLocation() : `boolean` | ||
| - location() : `string` | `undefined` | ||
|
|
||
| ## ExternalDocument | ||
| - description() : `string` | `undefined` | ||
| - extension(name) : `any` | `undefined` | ||
| - name : `string` | ||
| - hasDescription() : `boolean` | ||
| - hasExtension(name) : `boolean` | ||
| - name : `string` | ||
| - hasUrl() : `boolean` | ||
| - url() : `string` | `undefined` | ||
|
|
||
| ## Info | ||
| - contacts() : `Contact[]` | ||
| - description() : `string` | `undefined` | ||
| - extension(name) : `any` | `undefined` | ||
| - name : `string` | ||
| - externalDocs() : `ExternalDocument` | `undefined` | ||
| - hasContacts() : `boolean` | ||
| - hasDescription() : `boolean` | ||
| - hasExtension(name) : `boolean` | ||
| - name : `string` | ||
| - hasExternalDocs() : `boolean` | ||
| - hasId() : `boolean` | ||
| - hasLicense() : `boolean` | ||
| - hasTags() : `boolean` | ||
| - hasTermsOfService() : `boolean` | ||
| - id() : `string` | `undefined` | ||
| - license() : `License` | `undefined` | ||
| - tags() : `Tag[]` | `undefined` | ||
| - termsOfService() : `string` | `undefined` | ||
| - title() : `string` | ||
| - version() : `string` | ||
|
|
||
| ## License | ||
| - extension(name) : `any` | `undefined` | ||
| - name : `string` | ||
| - hasExtension(name) : `boolean` | ||
| - name : `string` | ||
| - hasUrl() : `boolean` | ||
| - name() : `string` | ||
| - url() : `string` | `undefined` | ||
|
|
||
| ## Message | ||
| - binding(bindingProtocol) : `any` | `undefined` | ||
| - bindingProtocol : `enum{'amqp', 'amqps', 'http', 'https', 'jms', 'kafka', 'kafka-secure', 'mqtt', 'secure-mqtt', 'stomp', 'stomps', 'ws', 'wss'}` | ||
| - channels() : `Channel[]` | ||
| - contentType() : `string` | ||
| - correlationId() : `CorrelationId` | `undefined` | ||
| - description() : `string` | `undefined` | ||
| - examples() : `Map[string, any][]` | ||
| - extension(name) : `any` | `undefined` | ||
| - name : `string` | ||
| - hasBinding(bindingProtocol) : `boolean` | ||
| - bindingProtocol : `enum{'amqp', 'amqps', 'http', 'https', 'jms', 'kafka', 'kafka-secure', 'mqtt', 'secure-mqtt', 'stomp', 'stomps', 'ws', 'wss'}` | ||
| - hasCorrelationId() : `boolean` | ||
| - hasDescription() : `boolean` | ||
| - hasExtension(name) : `boolean` | ||
| - name : `string` | ||
| - hasHeaders() : `boolean` | ||
| - hasKnownSchemaFormat() : `boolean` | ||
| - hasName() : `boolean` | ||
| - hasSummary() : `boolean` | ||
| - hasTags() : `boolean` | ||
| - hasTitle() : `boolean` | ||
| - headers() : `Schema` | `undefined` | ||
| - name() : `string` | `undefined` | ||
| - operations() : `Operation[]` | ||
| - payload() : `Schema | any` | ||
| - `Schema` type for all [known schema formats](https://www.asyncapi.com/docs/specifications/2.0.0#messageObjectSchemaFormatTable). Otherwise, `any`. | ||
| - schemaFormat() : `string` | ||
| - summary() : `string` | `undefined` | ||
| - tags() : `Tag[]` | `undefined` | ||
| - title() : `string` | `undefined` | ||
| - uid() : `string` | ||
|
|
||
| ## OAuthFlow | ||
| - authorizationUrl() : `string` | `undefined` | ||
| - extension(name) : `any` | `undefined` | ||
| - name : `string` | ||
| - hasExtension(name) : `boolean` | ||
| - name : `string` | ||
| - hasRefreshUrl() : `boolean` | ||
| - refreshUrl() : `string` | `undefined` | ||
| - scopes() : `Object.<string, string>` | `undefined` | ||
| - tokenUrl() : `string` | `undefined` | ||
|
|
||
| ## OAuthFlows | ||
| - authorizationCode() : `OAuthFlow` | `undefined` | ||
| - clientCredentials() : `OAuthFlow` | `undefined` | ||
| - extension(name) : `any` | `undefined` | ||
| - name : `string` | ||
| - hasAuthorizationCode() : `boolean` | ||
| - hasClientCredentials() : `boolean` | ||
| - hasExtension(name) : `boolean` | ||
| - name : `string` | ||
| - hasImplicit() : `boolean` | ||
| - hasPassword() : `boolean` | ||
| - implicit() : `OAuthFlow` | `undefined` | ||
| - password() : `OAuthFlow` | `undefined` | ||
|
|
||
| ## Operation | ||
| - binding(bindingProtocol) : `any` | `undefined` | ||
| - bindingProtocol : `enum{'amqp', 'amqps', 'http', 'https', 'jms', 'kafka', 'kafka-secure', 'mqtt', 'secure-mqtt', 'stomp', 'stomps', 'ws', 'wss'}` | ||
| - channels() : `Channel[]` | ||
| - description() : `string` | `undefined` | ||
| - extension(name) : `any` | `undefined` | ||
| - name : `string` | ||
| - externalDocs() : `ExternalDocument` | `undefined` | ||
| - hasBinding(bindingProtocol) : `boolean` | ||
| - bindingProtocol : `enum{'amqp', 'amqps', 'http', 'https', 'jms', 'kafka', 'kafka-secure', 'mqtt', 'secure-mqtt', 'stomp', 'stomps', 'ws', 'wss'}` | ||
| - hasDescription() : `boolean` | ||
| - hasExtension(name) : `boolean` | ||
| - name : `string` | ||
| - hasMultipleMessages() : `boolean` | ||
| - hasSummary() : `boolean` | ||
| - hasTags() : `boolean` | ||
| - id() : `string` | ||
| - isApplicationPublishing() : `boolean` | ||
| - isApplicationSubscribing() : `boolean` | ||
| - isClientPublishing() : `boolean` | ||
| - isClientSubscribing() : `boolean` | ||
| - messages() : `Message[]` | ||
| - server() : `Server` | ||
| - servers() : `Server[]` | ||
| - summary() : `string` | `undefined` | ||
| - tags() : `Tag[]` | ||
| - type() : `enum{'ClientSubscribing', 'ClientPublishing', 'ApplicationSubscribing', 'ApplicationPublishing}` | ||
|
|
||
| ## Schema | ||
| - $id() : `string` | ||
| - additionalItems : `Schema` | ||
| - additionalProperties : `boolean | Schema` | ||
| - allOf : `Schema` | ||
| - anyOf : `Schema` | ||
| - circularProps : `string[]` | ||
| - const : `any` | ||
| - contains : `Schema` | ||
| - contentEncoding : `string` | ||
| - contentMediaType : `string` | ||
| - default : `any` | ||
| - definitions : `Map[string, Schema]` | ||
| - dependencies : `Map[string, Schema|string[]]` | ||
| - deprecated : `boolean` | ||
| - discriminator : `string` | ||
| - else : `Schema` | ||
| - extension(name) : `any` | `undefined` | ||
| - name : `string` | ||
| - enum : `any[]` | ||
| - examples : `any[]` | ||
| - exclusiveMaximum() : `number` | ||
| - exclusiveMinimum : `number` | ||
| - format : `string` | ||
| - hasCircularProps : `boolean` | ||
| - hasExtension(name) : `boolean` | ||
| - name : `string` | ||
| - if : `Schema` | ||
| - isCircular : `boolean` | ||
| - items : `Schema | Schema[]` | ||
| - maximum() : `number` | ||
| - maxItems : `number` | ||
| - maxLength : `number` | ||
| - maxProperties : `number` | ||
| - minimum : `number` | ||
| - minItems : `number` | ||
| - minLength : `number` | ||
| - minProperties : `number` | ||
| - multipleOf() : `number` | ||
| - not : `Schema` | ||
| - oneOf : `Schema` | ||
| - pattern : `string` | ||
| - patternProperties : `Map[string, Schema]` | ||
| - properties : `Map[string, Schema]` | ||
| - property(name) : `Schema` | ||
| - name : `string` | ||
| - propertyNames : `Schema` | ||
| - readOnly : `boolean` | ||
| - required : `string` | ||
| - then : `Schema` | ||
| - title : `string` | ||
| - type : `string | string[]` | ||
| - uid() : `string` | ||
| - uniqueItems : `boolean` | ||
| - writeOnly : `boolean` | ||
|
|
||
| ## SecurityScheme | ||
| - bearerFormat() : `string` | `undefined` | ||
| - description() : `string` | ||
| - extension(name) : `any` | `undefined` | ||
| - name : `string` | ||
| - flows() : `OAuthFlows` | ||
| - hasBearerFormat() : `boolean` | ||
| - hasDescription() : `boolean` | ||
| - hasExtension(name) : `boolean` | ||
| - name : `string` | ||
| - in() : `enum{'user', 'password', 'query', 'header', 'cookie'}` | ||
| - openIdConnectUrl() : `string` | ||
| - scheme() : `string` | `undefined` | ||
| - scopes() : `string[]` | ||
| - type() : `enum{'userPassword', 'apiKey', 'X509', 'symmetricEncryption', 'asymmetricEncryption', 'httpApiKey', 'http', 'oauth2', 'openIdConnect'}` | ||
|
|
||
| ## ServerVariable | ||
| - allowedValues() : `any[]` | ||
| - defaultValue() : `string` | `undefined` | ||
| - description() : `string` | `undefined` | ||
| - examples() : `string[]` | ||
| - extension(name) : `any` | `undefined` | ||
| - name : `string` | ||
| - hasAllowedValues() : `boolean` | ||
| - hasDefaultValue() : `boolean` | ||
| - hasDescription() : `boolean` | ||
| - hasExtension(name) : `boolean` | ||
| - name : `string` | ||
| - hasName() : `boolean` | ||
| - name() : `string` | `undefined` | ||
|
|
||
| ## Server | ||
| - binding(bindingProtocol) : `any` | `undefined` | ||
| - bindingProtocol : `enum{'amqp', 'amqps', 'http', 'https', 'jms', 'kafka', 'kafka-secure', 'mqtt', 'secure-mqtt', 'stomp', 'stomps', 'ws', 'wss'}` | ||
| - description() : `string` | `undefined` | ||
| - extension(name) : `any` | `undefined` | ||
| - name : `string` | ||
| - hasBinding(bindingProtocol) : `boolean` | ||
| - bindingProtocol : `enum{'amqp', 'amqps', 'http', 'https', 'jms', 'kafka', 'kafka-secure', 'mqtt', 'secure-mqtt', 'stomp', 'stomps', 'ws', 'wss'}` | ||
| - hasDescription() : `boolean` | ||
| - hasExtension(name) : `boolean` | ||
| - name : `string` | ||
| - hasName() : `boolean` | ||
| - hasProtocol() : `boolean` | ||
| - hasProtocolVersion() : `boolean` | ||
| - hasUrl() : `boolean` | ||
| - name() : `string` | `undefined` | ||
| - operations() : `Operation[]` | ||
| - protocol() : `string` | `undefined` | ||
| - protocolVersion() : `string` | `undefined` | ||
| - securitySchemes() : `SecurityScheme[]` | ||
| - url() : `string` | `undefined` | ||
| - variables() : `ServerVariable[]` | ||
|
|
||
| ## Tag | ||
| - description() : `string` | `undefined` | ||
| - extension(name) : `any` | `undefined` | ||
| - name : `string` | ||
| - externalDocs() : `ExternalDocument` | `undefined` | ||
| - hasDescription() : `boolean` | ||
| - hasExtension(name) : `boolean` | ||
| - name : `string` | ||
| - hasExternalDocs() : `boolean` | ||
| - name() : `string` |