mirror of
https://github.com/adidas/api-guidelines.git
synced 2025-10-25 15:19:19 +00:00
89 lines
2.8 KiB
Markdown
89 lines
2.8 KiB
Markdown
# Channels
|
||
|
||
All AsyncAPI specs **MUST** include definitions for the channels (Kafka topics) including:
|
||
|
||
* Description of the topic
|
||
* Servers in which the topic is available
|
||
* This is a reference to one of the server identifiers included in the servers section
|
||
* publish/subscribe operations
|
||
* Operation ID
|
||
* Summary or short description for the operation
|
||
* Description for the operation
|
||
* Security schemes
|
||
* Tags
|
||
* External Docs
|
||
* Message details
|
||
|
||
In addition to those supported fields, it **MAY** be possible to use extension attributes (using the x- prefix) to specify specific configuration parameters and metadata. In so, the recommended attributes to use are:
|
||
|
||
* x-metadata
|
||
* To include additional configuration specific to your team or project
|
||
* x-configurations
|
||
* To include Kafka configuration parameters and producers/consumers
|
||
|
||
As the parameters can be different per environment, it is very convenient to add an additional level for the environment.
|
||
|
||
As part of the publish/subscribe operations, the spec **SHOULD** specify the different Kafka clients currently consuming from the different topics for each cluster/environment. For this, the extended attributes x-producers and x-consumers will be used.
|
||
|
||
```yaml
|
||
...
|
||
channels:
|
||
namespace.source.event.topic-name:
|
||
description: 'A description of the purpose of the topic and the contained information'
|
||
servers: ['playground-dev', 'playground-sit', 'playground-pro']
|
||
x-metadata:
|
||
myField1: 'myValue1'
|
||
myField2: 'myValue2'
|
||
x-configurations:
|
||
playground.dev:
|
||
kafka:
|
||
partitions: '12'
|
||
replicas: '1'
|
||
topicConfiguration:
|
||
min.insync.replicas: '1'
|
||
retention.ms: '2592000000'
|
||
playground.sit:
|
||
kafka:
|
||
partitions: '12'
|
||
replicas: '2'
|
||
topicConfiguration:
|
||
min.insync.replicas: '1'
|
||
retention.ms: '2592000000'
|
||
publish:
|
||
operationId: 'producer'
|
||
summary: 'Description for the operation'
|
||
description: 'An extensive explanation about the operation'
|
||
security:
|
||
- producerAcl: []
|
||
tags:
|
||
- name: 'tagA'
|
||
- name: 'tagB'
|
||
x-producers:
|
||
playground.dev:
|
||
- 'producer1'
|
||
- 'producer2'
|
||
playground.sit:
|
||
- 'producer1'
|
||
- 'producer2'
|
||
playground.pro:
|
||
- 'producer3'
|
||
- 'producer4'
|
||
externalDocs:
|
||
description: 'documentation'
|
||
url: 'http://confluence.adidas.fdp/catalogue/myTopic'
|
||
...
|
||
subscribe:
|
||
operationId: 'consumer'
|
||
...
|
||
x-consumers:
|
||
playground.dev:
|
||
- 'consumer1'
|
||
- 'consumer2'
|
||
playground.sit:
|
||
- 'consumer1'
|
||
- 'consumer2'
|
||
playground.pro:
|
||
- 'consumer3'
|
||
...
|
||
```
|