diff --git a/README.md b/README.md index f084330..3fef432 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # 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. @@ -10,7 +11,7 @@ For example, `Buy five watermelons` is the intent for `Going to the fruit 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 the API is missing an intent, please create a feature request with it. -Find all Parser API versions and definitions [here](docs). +Find the documentation for the current Parser API in [docs/api.md](docs/api.md). ## Design @@ -28,6 +29,7 @@ Each parser will therefore maintain its own compatibility matrix between which s ### Models These are the most important models in this API: + - **AsyncAPIDocument** is the root model. Most of the intents are here, so users don't need to navigate through the object hierarchy. - **Binding** is a mechanism to define protocol-specific information. - **Channel** describes a `topic`/`channel` a Message is transmitted over by some Operation. @@ -39,15 +41,18 @@ These are the most important models in this API: - **ExternalDocumention** contains external documentation source described by External Documentation. - **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. +- **Message** represents a message in your message-driven architecture. They can relate to Operations and Channels, but the relationship is not mandatory. - **MessageExample** defines sample payload and headers examples of the described Message. - **MessageTrait** defines reusable Message parts. - **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. +- **OperationReply** describes the reply characteristic in a request-reply Operation. +- **OperationReplyAddress** defines the address for the Operation Reply. - **OperationTrait** defines reusable Operation parts. - **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/latest#schemaObject. -- **SecurityScheme** represents security specifications for servers. +- **SecurityRequirement** represents used Security Scheme as security mechanism for Server and Operation with possible scopes. +- **SecurityScheme** represents security specification for Server and Operation. - **Server** represents a Server in your message-driven architecture. Application or Client always wants to connect to some server. - **ServerVariable** represents a Server Variable for server URL template substitution. - **Tag** contains metadata described by Tag. @@ -56,6 +61,7 @@ These are the most important models in this API: > Each model described has its corresponding collection model (except **AsyncAPIDocument**), such as **Servers**. ## Development + To avoid polluting the API with intents that have no clear 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. diff --git a/docs/v1.md b/docs/api.md similarity index 86% rename from docs/v1.md rename to docs/api.md index 7f07eeb..a636b02 100644 --- a/docs/v1.md +++ b/docs/api.md @@ -1,4 +1,4 @@ -# AsyncAPI Parser API v1.0.0 +# AsyncAPI Parser API v2.0.0 ## AsyncAPIDocument - version(): `string` @@ -40,8 +40,15 @@ - operations(): `Operations` - messages(): `Messages` - parameters(): `ChannelParameters` +- hasTitle(): `boolean` +- title(): `string` | `undefined` +- hasSummary(): `boolean` +- summary(): `string` | `undefined` - hasDescription(): `boolean` - description(): `string` | `undefined` +- hasExternalDocs(): `boolean` +- externalDocs(): `ExternalDocumention` | `undefined` +- tags(): `Tags` - bindings(): `Bindings` - extensions(): `Extensions` @@ -51,6 +58,7 @@ - filterBy(filter: `(channel: Channel) => boolean`): `Channel[]` - filterBySend(): `Channel[]` - filterByReceive(): `Channel[]` +- filterByTags(tags: `string[]`): `Channel[]` - get(id: `string`): `Channel` | `undefined` - has(id: `string`): `boolean` @@ -81,8 +89,12 @@ - serverVariables(): `ServerVariables` - operationTraits(): `OperationTraits` - messageTraits(): `MessageTraits` +- replies(): `OperationReplies` +- replyAddresses(): `OperationReplyAddresses` - correlationIds(): `CorrelationIds` - securitySchemes(): `SecuritySchemes` +- tags(): `Tags`; +- externalDocs(): `ExternalDocumentations`; - serverBindings(): `Map` - channelBindings(): `Map` - operationBindings(): `Map` @@ -123,6 +135,7 @@ - has(id: `string`): `boolean` ## ExternalDocumention +- id(): `string` | `undefined` - url(): `string` - hasDescription(): `boolean` - description(): `string` | `undefined` @@ -154,7 +167,8 @@ ## Message - id(): `string` -- schemaFormat(): `string` +- hasSchemaFormat(): `boolean` +- schemaFormat(): `string` | `undefined` - hasMessageId(): `boolean` - messageId(): `string` | `undefined` - hasCorrelationId(): `boolean` @@ -190,6 +204,7 @@ - filterBy(filter: `(message: Message) => boolean`): `Message[]` - filterBySend(): `Message[]` - filterByReceive(): `Message[]` +- filterByTags(tags: `string[]`): `Message[]` - get(id: `string`): `Message` | `undefined` - has(id: `string`): `boolean` @@ -211,7 +226,8 @@ ## MessageTrait - id(): `string` -- schemaFormat(): `string` +- hasSchemaFormat(): `boolean` +- schemaFormat(): `string` | `undefined` - hasMessageId(): `boolean` - messageId(): `string` | `undefined` - hasCorrelationId(): `boolean` @@ -270,6 +286,8 @@ - isReceive(): `boolean` - hasOperationId(): `boolean` - operationId(): `string` | `undefined` +- hasTitle(): `boolean` +- title(): `string` | `undefined` - hasSummary(): `boolean` - summary(): `string` | `undefined` - hasDescription(): `boolean` @@ -281,6 +299,7 @@ - servers(): `Servers` - channels(): `Channels` - messages(): `Messages` +- reply(): `OperationReply` | `undefined` - traits(): `OperationTraits` - bindings(): `Bindings` - extensions(): `Extensions` @@ -291,13 +310,46 @@ - filterBy(filter: `(operation: Operation) => boolean`): `Operation[]` - filterBySend(): `Operation[]` - filterByReceive(): `Operation[]` +- filterByTags(tags: `string[]`): `Operation[]` - get(id: `string`): `Operation` | `undefined` - has(id: `string`): `boolean` +## OperationReply +- id(): `string` | `undefined` +- hasAddress(): `boolean` +- address(): `OperationReplyAddress` | `undefined` +- hasChannel(): `boolean` +- channel(): `Channel` | `undefined` +- messages(): `Messages` +- extensions(): `Extensions` + +## OperationReplies +- all(): `OperationReply[]` +- isEmpty(): `boolean` +- filterBy(filter: `(reply: OperationReply) => boolean`): `OperationReply[]` +- get(id: `string`): `OperationReply` | `undefined` +- has(id: `string`): `boolean` + +## OperationReplyAddress +- id(): `string` | `undefined` +- location(): `string` +- hasDescription(): `boolean` +- description(): `string` | `undefined` +- extensions(): `Extensions` + +## OperationReplyAddresses +- all(): `OperationReplyAddress[]` +- isEmpty(): `boolean` +- filterBy(filter: `(address: OperationReplyAddress) => boolean`): `OperationReplyAddress[]` +- get(id: `string`): `OperationReplyAddress` | `undefined` +- has(id: `string`): `boolean` + ## OperationTrait - id(): `string` - hasOperationId(): `boolean` - operationId(): `string` | `undefined` +- hasTitle(): `boolean` +- title(): `string` | `undefined` - hasSummary(): `boolean` - summary(): `string` | `undefined` - hasDescription(): `boolean` @@ -362,6 +414,7 @@ - propertyNames(): `Schema` | `undefined` - readOnly(): `boolean` | `undefined` - required(): `string[]` | `undefined` +- schemaFormat(): `string` - then(): `Schema` | `undefined` - title(): `string` | `undefined` - type(): `string` | `string[]` | `undefined` @@ -415,17 +468,26 @@ ## Server - id(): `string` - url(): `string` +- host(): `string` - protocol(): `string` +- hasPathname(): `boolean` +- pathname(): `string` | `undefined` - hasProtocolVersion(): `boolean` - protocolVersion(): `string` | `undefined` +- hasTitle(): `boolean` +- title(): `string` | `undefined` +- hasSummary(): `boolean` +- summary(): `string` | `undefined` - hasDescription(): `boolean` - description(): `string` | `undefined` - variables(): `ServerVariables` - security(): `SecurityRequirements[]` +- hasExternalDocs(): `boolean` +- externalDocs(): `ExternalDocumention` | `undefined` +- tags(): `Tags` - channels(): `Channels` - operations(): `Operations` - messages(): `Messages` -- tags(): `Tags` - bindings(): `Bindings` - extensions(): `Extensions` @@ -435,6 +497,7 @@ - filterBy(filter: `(server: Server) => boolean`): `Server[]` - filterBySend(): `Server[]` - filterByReceive(): `Server[]` +- filterByTags(tags: `string[]`): `Server[]` - get(id: `string`): `Server` | `undefined` - has(id: `string`): `boolean` @@ -457,6 +520,7 @@ - has(id: `string`): `boolean` ## Tag +- id(): `string` | `undefined` - name(): `string` - hasDescription(): `boolean` - description(): `string` | `undefined`