The HTTP Protocol Binding for CloudEvents defines how events are mapped to HTTP 1.1 request and response messages.
This document is a working draft.
- 1.1. Conformance
- 1.2. Relation to HTTP
- 1.3. Content Modes
- 1.4. Event Formats
- 1.5. Security
- 2.1. datacontenttype Attribute
- 2.2. data
- 3.1. Binary Content Mode
- 3.2. Structured Content Mode
- 3.3. Batched Content Mode
CloudEvents is a standardized and protocol-agnostic definition of the structure and metadata description of events. This specification defines how the elements defined in the CloudEvents specification are to be used in HTTP 1.1 requests and response messages.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.
This specification does not prescribe rules constraining the use or handling of specific HTTP methods, and it also does not constrain the HTTP target resource that is used for transferring or soliciting events.
Events can be transferred with all standard or application-defined HTTP request methods that support payload body transfers. Events can be also be transferred in HTTP responses and with all HTTP status codes that permit payload body transfers.
All examples herein that show HTTP methods, HTTP target URIs, and HTTP status codes are non-normative illustrations.
This specification also applies equivalently to HTTP/2 (RFC7540), which is compatible with HTTP 1.1 semantics.
This specification defines three content modes for transferring events: 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 is placed into the
HTTP request, or response, body as-is, with the datacontenttype attribute
value declaring its media type in the HTTP Content-Type header; all other
event attributes are mapped to HTTP headers.
In the structured content mode, event metadata attributes and event data are placed into the HTTP request or response body using an event format that supports structured-mode messages.
In the batched content mode, event metadata attributes and event data of multiple events are batched into a single HTTP request or response body using an event format that supports batching structured-mode messages.
Event formats, used with the structured content mode, define how an event is expressed in a particular data format. All implementations of this specification that support the structured content mode MUST support the non-batching JSON event 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.
This specification does not introduce any new security features for HTTP, or mandate specific existing features to be used. This specification applies identically to HTTP over TLS.
This specification does not further define any of the core CloudEvents event attributes.
This mapping is intentionally robust against changes, including the addition and removal of event attributes, and also accommodates vendor extensions to the event metadata.
The datacontenttype attribute is assumed to contain a RFC2046
compliant media-type expression.
data is assumed to contain opaque application data that is encoded as declared
by the datacontenttype attribute.
An application is free to hold the information in any in-memory representation
of its choosing, but as the value is transposed into HTTP as defined in this
specification, the assumption is that the data value is made available as a
sequence of bytes.
For instance, if the declared datacontenttype is
application/json;charset=utf-8, the expectation is that the data value is
made available as UTF-8 encoded JSON text to HTTP.
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 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, the receiver uses structured mode. If the
value 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
treat the event as binary and forward it to another party as-is.
When the Content-Type header is not prefixed with the CloudEvents media type,
being able to know when the message ought to be attempted to be parsed as a
CloudEvent can be a challenge. While this specification can not mandate that
senders do not include any of the CloudEvents HTTP headers when the message
is not a CloudEvent, it would be reasonable for a receiver to assume that if
the message has all of the mandatory CloudEvents attributes as HTTP headers
then it's probably a CloudEvent. However, as with all CloudEvent messages, if
it does not adhere to all of the normative language of this specification
then it is not a valid CloudEvent.
The binary content mode accommodates any shape of event data, and allows for efficient transfer and without transcoding effort.
For the binary mode, the HTTP Content-Type header value corresponds to
(MUST be populated from or written to) the CloudEvents datacontenttype
attribute. Note that a ce-datacontenttype HTTP header MUST NOT also be
present in the message.
The data byte-sequence is used as the HTTP message body.
All other CloudEvents attributes, including extensions, MUST be individually mapped to and from distinct HTTP message header.
CloudEvents extensions that define their own attributes MAY define a secondary
mapping to HTTP headers for those attributes, especially if specific attributes
need to align with HTTP features or with other specifications that have explicit
HTTP header bindings. Note that these attributes MUST also still appear in the
HTTP message as HTTP headers with the ce- prefix as noted in
HTTP Header Names.
Except where noted, all CloudEvents context attributes, including extensions,
MUST be mapped to HTTP headers with the same name as the attribute name but
prefixed with ce-.
Examples:
* `time` maps to `ce-time`
* `id` maps to `ce-id`
* `specversion` maps to `ce-specversion`
Note: per the HTTP specification, header names are case-insensitive.
The value for each HTTP header is constructed from the respective attribute type's canonical string representation.
Some CloudEvents metadata attributes can contain arbitrary UTF-8 string content, and per RFC7230, section 3, HTTP headers MUST only use printable characters from the US-ASCII character set, and are terminated by a CRLF sequence with OPTIONAL whitespace around the header value.
String values MUST be percent-encoded as described in RFC3986, section 2.4 before applying the header encoding rules described in [RFC7230, section 3.2.6][rfc7230-section-3-2s6].
When decoding an HTTP message into a CloudEvent, these rules MUST be applied in reverse -- RFC7230, section 3.2.6 decoding to an ASCII string, and then a single round of percent-decoding as described in RFC3986, section 2.4 to produce a valid UTF-8 String. (Note that applying percent-decoding an incorrect number of times can result in message corruption or security issues.)
This example shows the binary mode mapping of an event with an HTTP POST request:
POST /someresource HTTP/1.1
Host: webhook.example.com
ce-specversion: 1.x-wip
ce-type: com.example.someevent
ce-time: 2018-04-05T03:56:24Z
ce-id: 1234-1234-1234
ce-source: /mycontext/subcontext
.... further attributes ...
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
{
... application data ...
}
This example shows a response containing an event:
HTTP/1.1 200 OK
ce-specversion: 1.x-wip
ce-type: com.example.someevent
ce-time: 2018-04-05T03:56:24Z
ce-id: 1234-1234-1234
ce-source: /mycontext/subcontext
.... further attributes ...
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
{
... application data ...
}
The structured content mode keeps event metadata and data together in the payload, allowing simple forwarding of the same event across multiple routing hops, and across multiple protocols.
The HTTP Content-Type header MUST be set to the media type of
an event format.
Example for the JSON format:
Content-Type: application/cloudevents+json; charset=UTF-8
The chosen event format defines how all attributes, and
data, are represented.
The event metadata and data is then rendered in accordance with the event format specification and the resulting data becomes the HTTP message body.
Implementations MAY include the same HTTP headers as defined for the binary mode.
All CloudEvents metadata attributes MUST be mapped into the payload, even if they are also mapped into HTTP headers.
This example shows a JSON event format encoded event, sent with a PUT request:
PUT /myresource HTTP/1.1
Host: webhook.example.com
Content-Type: application/cloudevents+json; charset=utf-8
Content-Length: nnnn
{
"specversion" : "1.x-wip",
"type" : "com.example.someevent",
... further attributes omitted ...
"data" : {
... application data ...
}
}
This example shows a JSON encoded event returned in a response:
HTTP/1.1 200 OK
Content-Type: application/cloudevents+json; charset=utf-8
Content-Length: nnnn
{
"specversion" : "1.x-wip",
"type" : "com.example.someevent",
... further attributes omitted ...
"data" : {
... application data ...
}
}
In the batched content mode several events are batched into a single HTTP request or response body. The chosen event format MUST define how a batch is represented. Based on the JSON format (that MUST be supported by any compliant implementation), the JSON Batch format is an event format that supports batching.
The HTTP Content-Type header MUST be set to the media type of
an event format.
Example for the JSON Batch format:
Content-Type: application/cloudevents-batch+json; charset=UTF-8
The chosen event format defines how a batch of events and
all event attributes, and data, 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 batch MAY be empty. All batched CloudEvents MUST have the same specversion
attribute. Other attributes MAY differ, including the datacontenttype
attribute.
This example shows two batched CloudEvents, sent with a PUT request:
PUT /myresource HTTP/1.1
Host: webhook.example.com
Content-Type: application/cloudevents-batch+json; charset=utf-8
Content-Length: nnnn
[
{
"specversion" : "1.x-wip",
"type" : "com.example.someevent",
... further attributes omitted ...
"data" : {
... application data ...
}
},
{
"specversion" : "1.x-wip",
"type" : "com.example.someotherevent",
... further attributes omitted ...
"data" : {
... application data ...
}
}
]
This example shows two batched CloudEvents returned in a response:
HTTP/1.1 200 OK
Content-Type: application/cloudevents-batch+json; charset=utf-8
Content-Length: nnnn
[
{
"specversion" : "1.x-wip",
"type" : "com.example.someevent",
... further attributes omitted ...
"data" : {
... application data ...
}
},
{
"specversion" : "1.x-wip",
"type" : "com.example.someotherevent",
... further attributes omitted ...
"data" : {
... application data ...
}
}
]
- RFC2046 Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types
- RFC2119 Key words for use in RFCs to Indicate Requirement Levels
- RFC2818 HTTP over TLS
- RFC3629 UTF-8, a transformation format of ISO 10646
- RFC3986 Uniform Resource Identifier (URI): Generic Syntax
- RFC4627 The application/json Media Type for JavaScript Object Notation (JSON)
- RFC4648 The Base16, Base32, and Base64 Data Encodings
- RFC6839 Additional Media Type Structured Syntax Suffixes
- RFC7159 The JavaScript Object Notation (JSON) Data Interchange Format
- RFC7230 Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing
- RFC7231 Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content
- RFC7540 Hypertext Transfer Protocol Version 2 (HTTP/2)