Skip to content

Commit 3fd0012

Browse files
LazzarettiLazzaretti
authored
AsyncAPI with CloudEvents (#1349)
* AsyncAPI with CloudEvents Adding a first draft according to #1276 Signed-off-by: Lazzaretti <fabrizio@lazzaretti.me> * add changes from code review - remove intorudcion - wrap the lines at 80 chars - s/should/will/ - create translation files he/CN Signed-off-by: Lazzaretti <fabrizio@lazzaretti.me> * fix: title naming Signed-off-by: Lazzaretti <fabrizio@lazzaretti.me> * Add short samples on how to add CloudEvents support to AsyncAPI Signed-off-by: Lazzaretti <fabrizio@lazzaretti.me> * Change links for asyncapi-traits to location after merging Signed-off-by: Lazzaretti <fabrizio@lazzaretti.me> --------- Signed-off-by: Lazzaretti <fabrizio@lazzaretti.me>
1 parent c932302 commit 3fd0012

File tree

6 files changed

+212
-0
lines changed

6 files changed

+212
-0
lines changed

‎cloudevents/languages/he/working-drafts/asyncapi.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# AsyncAPI With CloudEvents - Version 1.0.3-wip
2+
מסמך זה טרם תורגם. בבקשה תשתמשו [בגרסה האנגלית של המסמך](../../../working-drafts/asyncapi.md) לבינתיים.

‎cloudevents/languages/zh-CN/working-drafts/asyncapi.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# AsyncAPI With CloudEvents - Version 1.0.3-wip
2+
3+
本文档尚未被翻译，请先阅读英文[原版文档](../../../working-drafts/asyncapi.md) 。
4+
5+
如果您迫切地需要此文档的中文翻译，请[提交一个issue](https://github.com/cloudevents/spec/issues) ，
6+
我们会尽快安排专人进行翻译。

‎cloudevents/working-drafts/asyncapi-examples/light-switch-events-binary-kafka.yaml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# yaml-language-server: $schema=https://asyncapi.com/schema-store/3.0.0-without-$id.json
2+
asyncapi: 3.0.0
3+
info:
4+
title: Light Switch Events With CloudEvents as Headers (Binary Mode)
5+
version: 1.0.0
6+
description: Informes about light swich changes.
7+
operations:
8+
onOfficeLightSwitchChanged:
9+
title: Office light switch was triggered
10+
channel:
11+
$ref: '#/channels/officeLightSwitchChanged'
12+
action: receive
13+
14+
channels:
15+
officeLightSwitchChanged:
16+
address: 'lightswitch.office.changed'
17+
title: Office light switch changes
18+
messages:
19+
lightSwitchChanged:
20+
$ref: '#/components/messages/lightSwitchChanged'
21+
22+
components:
23+
messages:
24+
lightSwitchChanged:
25+
description: Light switch was triggered event with CloudEvents headers
26+
traits:
27+
- $ref: 'https://raw.githubusercontent.com/cloudevents/spec/main/cloudevents/working-drafts/asyncapi-traits/cloudevents-headers-kafka-binary.yaml'
28+
payload:
29+
type: object
30+
properties:
31+
lightSwitchId:
32+
type: integer
33+
examples:
34+
- 1
35+
position:
36+
type: string
37+
enum:
38+
- ON
39+
- OFF

‎cloudevents/working-drafts/asyncapi-examples/light-switch-events-structured-json.yaml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# yaml-language-server: $schema=https://asyncapi.com/schema-store/3.0.0-without-$id.json
2+
asyncapi: 3.0.0
3+
info:
4+
title: Light Switch Events With CloudEvents as Headers (Binary Mode)
5+
version: 1.0.0
6+
description: Informes about light swich changes.
7+
operations:
8+
onOfficeLightSwitchChanged:
9+
title: Office light switch was triggered
10+
channel:
11+
$ref: '#/channels/officeLightSwitchChanged'
12+
action: receive
13+
14+
channels:
15+
officeLightSwitchChanged:
16+
address: 'lightswitch.office.changed'
17+
title: Office light switch changes
18+
messages:
19+
lightSwitchChanged:
20+
$ref: '#/components/messages/lightSwitchChanged'
21+
22+
components:
23+
messages:
24+
lightSwitchChanged:
25+
description: Light switch was triggered event with CloudEvents headers
26+
payload:
27+
type: object
28+
allOf:
29+
- $ref: 'https://raw.githubusercontent.com/cloudevents/spec/v1.0.2/cloudevents/formats/cloudevents.json'
30+
properties:
31+
data:
32+
type: object
33+
properties:
34+
lightSwitchId:
35+
type: integer
36+
examples:
37+
- 1
38+
position:
39+
type: string
40+
enum:
41+
- ON
42+
- OFF

‎cloudevents/working-drafts/asyncapi-traits/cloudevents-headers-kafka-binary.yaml‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
name: cloudevents-headers-kafka-binary
2+
summary: Message headers for CloudEvents in binary content mode with Kafka (see https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/kafka-protocol-binding.md)
3+
headers:
4+
type: object
5+
required:
6+
- ce_id
7+
- ce_source
8+
- ce_specversion
9+
- ce_type
10+
properties:
11+
ce_id:
12+
type: string
13+
minLength: 1
14+
description: Identifies the event.
15+
examples:
16+
- "1234-1234-1234"
17+
ce_source:
18+
type: string
19+
format: uri-reference
20+
minLength: 1
21+
description: Identifies the context in which an event happened.
22+
examples:
23+
- "https://example.com/storage/tenant/container"
24+
ce_specversion:
25+
type: string
26+
description: The version of the CloudEvents specification which the event uses.
27+
enum:
28+
- "1.0"
29+
ce_type:
30+
type: string
31+
minLength: 1
32+
description: Describes the type of event related to the originating occurrence.
33+
examples:
34+
- "com.example.someevent"
35+
content-type:
36+
type: string
37+
description: Kafka default field to describing the content type of the data. Must be mapped directly to the CloudEvents datacontenttype attribute.
38+
examples:
39+
- "application/avro"
40+
- "application/json;charset=utf-8"
41+
ce_dataschema:
42+
type: string
43+
description: Identifies the schema that data adheres to.
44+
examples:
45+
- "http://registry.com/schema/v1/much.json"
46+
ce_subject:
47+
type: string
48+
description: Describes the subject of the event in the context of the event producer (identified by source)
49+
examples:
50+
- mynewfile.jpg
51+
ce_time:
52+
type: string
53+
format: date-time
54+
description: Timestamp of when the occurrence happened. Must adhere to RFC 3339.
55+
examples:
56+
- "2018-04-05T17:31:00Z"

‎cloudevents/working-drafts/asyncapi.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# AsyncAPI With CloudEvents - Version 1.0.3-wip
2+
3+
## Purpose
4+
5+
Asynchronous APIs, e.g., events, can be specified in AsyncAPI, similar to how
6+
RESTful APIs can be specified in [OpenAPI](https://swagger.io/specification/).
7+
When defining new events in an API-first approach it can be hard to add
8+
CloudEvents headers or fields according to spec. This makes following the
9+
standard harder. This document will clarify how CloudEvents headers can be
10+
specified in AsyncAPI.
11+
12+
## Usage
13+
14+
Depending on the protocol and the mode (binary/structured), the inclusion of the
15+
CloudEvents fields varies.
16+
17+
## Structured Mode
18+
19+
In structured mode, the entire event, attributes, and data are encoded in the
20+
message body. When using structured mode, the usage only varies depending on the
21+
serialization format:
22+
23+
| Format | Example                                                                 | Include                                  |
24+
| ------ | ----------------------------------------------------------------------- | ---------------------------------------- |
25+
| JSON   | [Short Example](#json-example) [Full Example](./asyncapi-examples/light-switch-events-structured-json.yaml) | [Reference](../formats/cloudevents.json) |
26+
27+
### JSON Example
28+
29+
To add CloudEvents in structured mode, the following `allOf` reference needs to
30+
be added:
31+
32+
```yaml
33+
components:
34+
messages:
35+
messageKey:
36+
payload:
37+
type: object
38+
allOf:
39+
- $ref: 'https://raw.githubusercontent.com/cloudevents/spec/v1.0.2/cloudevents/formats/cloudevents.json'
40+
```
41+
42+
See also: [Full Example](./asyncapi-examples/light-switch-events-structured-json.yaml)
43+
44+
## Binary Mode
45+
46+
In binary mode, protocol-specific bindings are mapping fields to protocol
47+
content-type metadata property or headers; therefore, the AsyncAPI format needs
48+
to depend on the protocol:
49+
50+
| Protocol Binding                               | Example                                                              | Trait                                                            |
51+
| ---------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------- |
52+
| [Kafka](../bindings/kafka-protocol-binding.md) | [Short Example](#avro-example) [Full Example](./asyncapi-examples/light-switch-events-binary-kafka.yaml) | [Trait](./asyncapi-traits/cloudevents-headers-kafka-binary.yaml) |
53+
54+
### Avro Example
55+
56+
To add CloudEvents in binary mode, the following `traits` reference needs to
57+
be added:
58+
59+
```yaml
60+
components:
61+
messages:
62+
messageKey:
63+
traits:
64+
- $ref: 'https://raw.githubusercontent.com/cloudevents/spec/main/cloudevents/working-drafts/asyncapi-traits/cloudevents-headers-kafka-binary.yaml'
65+
```
66+
67+
See also: [Full Example](./asyncapi-examples/light-switch-events-binary-kafka.yaml)

0 commit comments

Comments
 (0)