From d7216e2f63b75bd8f761e3853fc6a12ddb707916 Mon Sep 17 00:00:00 2001 From: Christoph Neijenhuis Date: Wed, 23 Jan 2019 21:43:01 +0100 Subject: [PATCH] Move JSON Batch into JSON Format; more generic HTTP transport Signed-off-by: Christoph Neijenhuis --- http-transport-binding.md | 45 +++++++++++++---------- json-format.md | 76 +++++++++++++++++++++++++++++++++++++-- 2 files changed, 100 insertions(+), 21 deletions(-) diff --git a/http-transport-binding.md b/http-transport-binding.md index 2b96e5f82..b67487cb0 100644 --- a/http-transport-binding.md +++ b/http-transport-binding.md @@ -23,7 +23,7 @@ This document is a working draft. 3. [HTTP Message Mapping](#3-http-message-mapping) - 3.1. [Binary Content Mode](#31-binary-content-mode) - 3.2. [Structured Content Mode](#32-structured-content-mode) -- 3.3. [JSON Batch Content Mode](#33-json-batch-content-mode) +- 3.3. [Batched Content Mode](#33-batched-content-mode) 4. [References](#4-references) ## 1. Introduction @@ -60,7 +60,7 @@ which is compatible with HTTP 1.1 semantics. ### 1.3. Content Modes This specification defines three content modes for transferring events: -*structured*, *binary* and *JSON Batch*. Every compliant implementation SHOULD +*binary*, *structured* and *batched*. Every compliant implementation SHOULD support the *structured* and *binary* modes. In the *binary* content mode, the value of the event `data` attribute is placed @@ -72,9 +72,9 @@ In the *structured* content mode, event metadata attributes and event data are placed into the HTTP request or response body using an [event format](#14-event-formats). -In the *JSON Batch* content mode several events are batched into a single HTTP -request or response body. The payload is built on top of the -[JSON event format][JSON-format]. +In the *batched* content mode several events are batched into a single HTTP +request or response body using an [event format](#14-event-formats) that +supports batching. ### 1.4. Event Formats @@ -83,6 +83,9 @@ expressed in a particular data format. All implementations of this specification MUST support the [JSON event format][JSON-format], but MAY support any additional, including proprietary, formats. +Event formats MAY additionally define how a batch of events is expressed. Those +can be used with the *batched* content mode + ### 1.5. Security This specification does not introduce any new security features for HTTP, or @@ -129,15 +132,15 @@ The event binding is identical for both HTTP request and response messages. The content mode is chosen by the sender of the event, which is either the requesting or the responding party. Gestures that might allow solicitation of events using a particular mode might be defined by an application, but are not -defined here. The *JSON Batch* mode MUST NOT be used unless solicited, and the +defined here. The *batched* mode MUST NOT be used unless solicited, and the gesture SHOULD allow the receiver to choose the maximum size of a batch. The receiver of the event can distinguish between the three modes by inspecting the `Content-Type` header value. If the value is prefixed with the CloudEvents media type `application/cloudevents`, indicating the use of a known [event format](#14-event-formats), the receiver uses *structured* mode. If the value -is prefixed with `application/cloudevents-batch+json`, the receiver uses the -*JSON Batch* mode. Otherwise it defaults to *binary* mode. +is prefixed with `application/cloudevents-batch`, the receiver uses the +*batched* mode. Otherwise it defaults to *binary* mode. If a receiver detects the CloudEvents media type, but with an event format that it cannot handle, for instance `application/cloudevents+avro`, it MAY still @@ -337,18 +340,19 @@ Content-Length: nnnn ``` -### 3.3. JSON Batch Content Mode +### 3.3. Batched Content Mode -In the *JSON Batch* content mode several events are batched into a single HTTP -request or response body. The payload is a JSON array filled with CloudEvents -in the [JSON event format][JSON-format]. +In the *batched* content mode several events are batched into a single HTTP +request or response body. The chosen [event format](#14-event-formats) MUST +define how a batch is represented. Currently, the only format supporting +batching is the [JSON Batch Format][JSON-batch-format]. #### 3.3.1. HTTP Content-Type -The [HTTP `Content-Type`][Content-Type] header MUST be set to -`application/cloudevents-batch+json`. +The [HTTP `Content-Type`][Content-Type] header MUST be set to the media type of +an [event format](#14-event-formats). -An example: +Example for the [JSON Batch format][JSON-batch-format]: ``` text Content-Type: application/cloudevents-batch+json; charset=UTF-8 @@ -356,11 +360,13 @@ Content-Type: application/cloudevents-batch+json; charset=UTF-8 #### 3.3.2. Event Data Encoding -The payload is a [JSON Array][JSON-array], which contains CloudEvents rendered -in accordance with the [JSON event format][JSON-format] specification. The -resulting data becomes the HTTP message body. +The chosen [event format](#14-event-formats) defines how a batch of events and +all event attributes, including the `data` attribute, are represented. + +The batch of events is then rendered in accordance with the event format +specification and the resulting data becomes the HTTP message body. -The array MAY be empty (typically used in a HTTP response). +The batch MAY be empty (typically used in a HTTP response). All batched CloudEvents MUST have the same `specversion` attribute. Other attributes MAY differ, including the `contenttype` attribute. @@ -454,6 +460,7 @@ Content-Length: nnnn [CE]: ./spec.md [JSON-format]: ./json-format.md +[JSON-batch-format]: ./json-format.md#4-json-batch-format [Content-Type]: https://tools.ietf.org/html/rfc7231#section-3.1.1.5 [JSON-Value]: https://tools.ietf.org/html/rfc7159#section-3 [JSON-Array]: https://tools.ietf.org/html/rfc7159#section-5 diff --git a/json-format.md b/json-format.md index d831b0ef7..818727696 100644 --- a/json-format.md +++ b/json-format.md @@ -14,7 +14,8 @@ This document is a working draft. 1. [Introduction](#1-introduction) 2. [Attributes](#2-attributes) 3. [Envelope](#3-envelope) -4. [References](#4-references) +4. [JSON Batch Format](#4-json-batch-format) +5. [References](#5-references) ## 1. Introduction @@ -229,7 +230,77 @@ a `Map` or [JSON data](#31-special-handling-of-the-data-attribute) data: } ``` -## 4. References +## 4. JSON Batch Format + +In the *JSON Batch Format* several CloudEvents are batched into a single JSON +document. The document is a JSON array filled with CloudEvents in the +[JSON Event format][JSON-format]. + +Although the *JSON Batch Format* builds ontop of the *JSON Format*, it should +be considered as a separate format: a valid implementation of the *JSON Format* +doesn't have to support it. The *JSON Batch Format* MUST NOT be used when only +support for the *JSON Format* is indicated. + +### 4.1. Mapping CloudEvents + +This section defines how a batch of CloudEvents is mapped to JSON. + +The outermost JSON element is a [JSON Array][JSON-array], which contains +CloudEvents rendered in accordance with the [JSON event format][JSON-format] +specification. + +### 4.2. Envelope + +A JSON Batch of CloudEvents must use the media type +`application/cloudevents-batch+json`. + +### 4.3. Examples + +An example containing two CloudEvents: The first with `Binary`-valued data, the +second with JSON data. + +``` JSON +[ + { + "specversion" : "0.2", + "type" : "com.example.someevent", + "source" : "/mycontext/4", + "id" : "B234-1234-1234", + "time" : "2018-04-05T17:31:00Z", + "comexampleextension1" : "value", + "comexampleextension2" : { + "otherValue": 5 + }, + "contenttype" : "application/vnd.apache.thrift.binary", + "data" : "... base64 encoded string ..." + }, + { + "specversion" : "0.2", + "type" : "com.example.someotherevent", + "source" : "/mycontext/9", + "id" : "C234-1234-1234", + "time" : "2018-04-05T17:31:05Z", + "comexampleextension1" : "value", + "comexampleextension2" : { + "otherValue": 5 + }, + "contenttype" : "application/json", + "data" : { + "appinfoA" : "abc", + "appinfoB" : 123, + "appinfoC" : true + } + } +] +``` + +An example of an empty batch of CloudEvents (typically used in a response): + +```JSON +[] +``` + +## 5. References * [RFC2046][RFC2046] Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types @@ -250,6 +321,7 @@ a `Map` or [JSON data](#31-special-handling-of-the-data-attribute) data: [JSON-Number]: https://tools.ietf.org/html/rfc7159#section-6 [JSON-String]: https://tools.ietf.org/html/rfc7159#section-7 [JSON-Value]: https://tools.ietf.org/html/rfc7159#section-3 +[JSON-Array]: https://tools.ietf.org/html/rfc7159#section-5 [RFC2046]: https://tools.ietf.org/html/rfc2046 [RFC2119]: https://tools.ietf.org/html/rfc2119 [RFC3986]: https://tools.ietf.org/html/rfc3986