From 6f3e112c1cc37561cac74434c581c549b0499e76 Mon Sep 17 00:00:00 2001 From: John Fallows Date: Mon, 3 Jun 2024 10:28:54 -0700 Subject: [PATCH 1/6] Support Server-Sent Events protocol for AsyncAPI --- README.md | 1 + sse/README.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 64 insertions(+) create mode 100644 sse/README.md diff --git a/README.md b/README.md index 96e67ce1..466f5ab8 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,7 @@ This repository contains the specifications for each AsyncAPI protocol binding. * [NATS binding](./nats) * [Pulsar](./pulsar) * [Redis binding](./redis) +* [Server-Sent Events binding](./sse) * [SNS binding](./sns) * [Solace binding](./solace) * [SQS binding](./sqs) diff --git a/sse/README.md b/sse/README.md new file mode 100644 index 00000000..a99450fb --- /dev/null +++ b/sse/README.md @@ -0,0 +1,63 @@ +# Server Sent Events Bindings + +This document defines how to describe Server Sent Events-specific information on AsyncAPI. + +See the [Server-Sent Events protocol specification](protocolSpecification). + + + +## Version + +Current version is `0.1.0`. + + + + +## Server Binding Object + +This object MUST NOT contain any properties. Its name is reserved for future use. + + + + +## Channel Binding Object + +When using Server Sent Events, the channel represents a single logical message stream flowing from server to client. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +`method` | string | The HTTP method to use when establishing the request. Its value MUST be `GET`. +`query` | [Schema Object][schemaObject] \| [Reference Object](referenceObject) | A Schema object containing the definitions for each query parameter. This schema MUST be of type `object` and have a `properties` key. +`headers` | [Schema Object][schemaObject] \| [Reference Object](referenceObject) | A Schema object containing the definitions of the HTTP headers to use when establishing the request. This schema MUST be of type `object` and have a `properties` key. +`bindingVersion` | string | The version of this binding. If omitted, "latest" MUST be assumed. + +This object MUST contain only the properties defined above. + + + +## Operation Binding Object + +This object MUST NOT contain any properties. Its name is reserved for future use. + + + + +## Message Binding Object + +This object contains information about the message representation in SSE. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|:---:|--- +`event` | string | Server-sent event type, defaults to `message` if omitted, by the [SSE specification](protocolSpecification). | +`bindingVersion` | string | | The version of this binding. If omitted, "latest" MUST be assumed. + +This object MUST contain only the properties defined above. + + +[schemaObject]: https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#schemaObject +[referenceObject]: https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#referenceObject +[protocolSpecification]: https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events \ No newline at end of file From d644f1553559a852349241fb3e840f31fcd371e4 Mon Sep 17 00:00:00 2001 From: John Fallows Date: Thu, 6 Jun 2024 05:56:25 -0700 Subject: [PATCH 2/6] Fix link to SSE specification --- sse/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sse/README.md b/sse/README.md index a99450fb..2f6aed0b 100644 --- a/sse/README.md +++ b/sse/README.md @@ -2,7 +2,7 @@ This document defines how to describe Server Sent Events-specific information on AsyncAPI. -See the [Server-Sent Events protocol specification](protocolSpecification). +See the [Server-Sent Events protocol specification][protocolSpecification]. @@ -60,4 +60,4 @@ This object MUST contain only the properties defined above. [schemaObject]: https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#schemaObject [referenceObject]: https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#referenceObject -[protocolSpecification]: https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events \ No newline at end of file +[protocolSpecification]: https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events From 28e78fb9cdf23762b9813ccc8d96d569188ab0d7 Mon Sep 17 00:00:00 2001 From: John Fallows Date: Fri, 7 Jun 2024 12:10:22 -0700 Subject: [PATCH 3/6] Fix table formatting --- sse/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sse/README.md b/sse/README.md index 2f6aed0b..2569aadf 100644 --- a/sse/README.md +++ b/sse/README.md @@ -51,9 +51,9 @@ This object contains information about the message representation in SSE. ##### Fixed Fields Field Name | Type | Description ----|:---:|:---:|--- -`event` | string | Server-sent event type, defaults to `message` if omitted, by the [SSE specification](protocolSpecification). | -`bindingVersion` | string | | The version of this binding. If omitted, "latest" MUST be assumed. +---|:---:|--- +`event` | string | Server-sent event type, defaults to `message` if omitted, by the [SSE specification][protocolSpecification]. | +`bindingVersion` | string | The version of this binding. If omitted, "latest" MUST be assumed. This object MUST contain only the properties defined above. From 75bc30a9f76be48cd688917e233972c2be524451 Mon Sep 17 00:00:00 2001 From: John Fallows Date: Mon, 10 Jun 2024 18:04:30 -0700 Subject: [PATCH 4/6] Remove constant `GET` method. --- sse/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/sse/README.md b/sse/README.md index 2569aadf..aa66229d 100644 --- a/sse/README.md +++ b/sse/README.md @@ -28,7 +28,6 @@ When using Server Sent Events, the channel represents a single logical message s Field Name | Type | Description ---|:---:|--- -`method` | string | The HTTP method to use when establishing the request. Its value MUST be `GET`. `query` | [Schema Object][schemaObject] \| [Reference Object](referenceObject) | A Schema object containing the definitions for each query parameter. This schema MUST be of type `object` and have a `properties` key. `headers` | [Schema Object][schemaObject] \| [Reference Object](referenceObject) | A Schema object containing the definitions of the HTTP headers to use when establishing the request. This schema MUST be of type `object` and have a `properties` key. `bindingVersion` | string | The version of this binding. If omitted, "latest" MUST be assumed. From fce8154be77ff941b1c360222ebb09f31f880875 Mon Sep 17 00:00:00 2001 From: John Fallows Date: Thu, 20 Jun 2024 16:09:59 -0700 Subject: [PATCH 5/6] Simplify to define Message Binding Object only and use http server protocol --- sse/README.md | 17 ++++------------- 1 file changed, 4 insertions(+), 13 deletions(-) diff --git a/sse/README.md b/sse/README.md index aa66229d..593f9da5 100644 --- a/sse/README.md +++ b/sse/README.md @@ -4,6 +4,8 @@ This document defines how to describe Server Sent Events-specific information on See the [Server-Sent Events protocol specification][protocolSpecification]. +Server-Sent Events requires `http` protocol, so the SSE [Message Binding Object](#message) below is appropriate for Servers with protocol `http`. + ## Version @@ -22,17 +24,8 @@ This object MUST NOT contain any properties. Its name is reserved for future use ## Channel Binding Object -When using Server Sent Events, the channel represents a single logical message stream flowing from server to client. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -`query` | [Schema Object][schemaObject] \| [Reference Object](referenceObject) | A Schema object containing the definitions for each query parameter. This schema MUST be of type `object` and have a `properties` key. -`headers` | [Schema Object][schemaObject] \| [Reference Object](referenceObject) | A Schema object containing the definitions of the HTTP headers to use when establishing the request. This schema MUST be of type `object` and have a `properties` key. -`bindingVersion` | string | The version of this binding. If omitted, "latest" MUST be assumed. +This object MUST NOT contain any properties. Its name is reserved for future use. -This object MUST contain only the properties defined above. @@ -51,12 +44,10 @@ This object contains information about the message representation in SSE. Field Name | Type | Description ---|:---:|--- -`event` | string | Server-sent event type, defaults to `message` if omitted, by the [SSE specification][protocolSpecification]. | +`event` | string | Server-sent event type, typically `message`, to specify allowed SSE message types. | `bindingVersion` | string | The version of this binding. If omitted, "latest" MUST be assumed. This object MUST contain only the properties defined above. -[schemaObject]: https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#schemaObject -[referenceObject]: https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#referenceObject [protocolSpecification]: https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events From f6cc32fda4d2ebee613f6bb013500ece68d43737 Mon Sep 17 00:00:00 2001 From: John Fallows Date: Thu, 20 Jun 2024 16:16:49 -0700 Subject: [PATCH 6/6] Clarify server protocol as http or https --- sse/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sse/README.md b/sse/README.md index 593f9da5..999eddf9 100644 --- a/sse/README.md +++ b/sse/README.md @@ -4,7 +4,7 @@ This document defines how to describe Server Sent Events-specific information on See the [Server-Sent Events protocol specification][protocolSpecification]. -Server-Sent Events requires `http` protocol, so the SSE [Message Binding Object](#message) below is appropriate for Servers with protocol `http`. +Server-Sent Events requires `http` protocol, so the SSE [Message Binding Object](#message) below is appropriate for AsyncAPI Servers with protocol `http` or `https`.