From 232bb559ae8db52747953ee7be8e309d6c7c5a1f Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Tue, 14 Nov 2023 18:08:00 +0100 Subject: [PATCH 01/39] Initial draft for bindings with Kafka tutorials --- pages/docs/tutorials/bindings-with-kafka.md | 66 +++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 pages/docs/tutorials/bindings-with-kafka.md diff --git a/pages/docs/tutorials/bindings-with-kafka.md b/pages/docs/tutorials/bindings-with-kafka.md new file mode 100644 index 000000000000..37172876e996 --- /dev/null +++ b/pages/docs/tutorials/bindings-with-kafka.md @@ -0,0 +1,66 @@ +--- +title: Bindings with Kafka +description: In this tutorial, you'll learn how bindings with Kafka works and different ways to utilize bindings +weight: 150 +--- + +## Introduction + +In this tutorial, you will learn how bindings with Kafka works. You will learn how to extend your AsyncAPI document with Protocol-specific information, such as how to use Kafka bindings. You will also learn about server bindings and channel bindings. + +## Background Context + +**What is Kafka** +Kafka is a messaging system that allows for the efficient handling and processing of data streams. + +**What is binding?** +In the context of Kafka, "bindings" refer to the connections between Kafka and other systems or applications. There are several levels of bindings as described below: + + + +- Server Binding +- Channel binding +- Operation Binding + +**How binding works in Kafka** +You must understand some essential parts of the process to understand how binding works. + +Kafka as a messaging system - Think of Kafka as a courier service - A messaging system that handles sending and receiving messages between applications. + +Producers and Consumers - Producers send packages (messages) to the courier service (Kafka), and consumers receive these packages. + +Topics: Kafka organizes messages into categories. Just like a courier service, it will group items based on several cases, like how heavy the package is or the arrival date. It’s like having different boxes for different messages. + +Bindings: Bindings are relevant when integrating Kafka with other programs or services. A binding is a specific agreement or configuration that governs how an application connects to and interacts with Kafka. It can include information such as: + +- Which topics should an application read from or write to? +- How should messages be formatted? +- What are the rules for interacting with various forms of data or messages? + +Bindings are vital because they ensure that applications and Kafka can communicate effectively with each other's message formats, protocols, and expectations, ensuring data flows securely and efficiently within a system. + + + +Now, let’s see how to use bindings with Kafka. + +## Installation Guide + + + + +## Summary +## Next Steps + + From b5fdf9f3861e7c1394dd1f2071179c5dba6c8540 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Wed, 15 Nov 2023 06:47:43 +0100 Subject: [PATCH 02/39] Added feedback from Ludovic and moved the questions to the comments section --- pages/docs/tutorials/bindings-with-kafka.md | 18 +++++------------- 1 file changed, 5 insertions(+), 13 deletions(-) diff --git a/pages/docs/tutorials/bindings-with-kafka.md b/pages/docs/tutorials/bindings-with-kafka.md index 37172876e996..5e5a12667d9c 100644 --- a/pages/docs/tutorials/bindings-with-kafka.md +++ b/pages/docs/tutorials/bindings-with-kafka.md @@ -6,7 +6,7 @@ weight: 150 ## Introduction -In this tutorial, you will learn how bindings with Kafka works. You will learn how to extend your AsyncAPI document with Protocol-specific information, such as how to use Kafka bindings. You will also learn about server bindings and channel bindings. +In this tutorial, you will learn how bindings with Kafka works. You will learn how to extend your AsyncAPI document with Protocol-specific information, such as how to specify kafka topic-specific configurations or how to define kafka message key content. ## Background Context @@ -16,11 +16,10 @@ Kafka is a messaging system that allows for the efficient handling and processin **What is binding?** In the context of Kafka, "bindings" refer to the connections between Kafka and other systems or applications. There are several levels of bindings as described below: - -- Server Binding -- Channel binding -- Operation Binding +- Server Bindings +- Channel Bindings +- Operation Bindings **How binding works in Kafka** You must understand some essential parts of the process to understand how binding works. @@ -37,7 +36,7 @@ Bindings: Bindings are relevant when integrating Kafka with other programs or se - How should messages be formatted? - What are the rules for interacting with various forms of data or messages? -Bindings are vital because they ensure that applications and Kafka can communicate effectively with each other's message formats, protocols, and expectations, ensuring data flows securely and efficiently within a system. +Bindings are important because they indicate how Kafka components are configured. From 94e4f50809e905a467e42acff9926e7429186178 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Wed, 15 Nov 2023 07:17:58 +0100 Subject: [PATCH 03/39] Added the first version of a diagram --- pages/docs/tutorials/bindings-with-kafka.md | 39 +++++++++++++++++---- 1 file changed, 32 insertions(+), 7 deletions(-) diff --git a/pages/docs/tutorials/bindings-with-kafka.md b/pages/docs/tutorials/bindings-with-kafka.md index 5e5a12667d9c..2fb7b520f537 100644 --- a/pages/docs/tutorials/bindings-with-kafka.md +++ b/pages/docs/tutorials/bindings-with-kafka.md @@ -11,9 +11,11 @@ In this tutorial, you will learn how bindings with Kafka works. You will learn h ## Background Context **What is Kafka** + Kafka is a messaging system that allows for the efficient handling and processing of data streams. **What is binding?** + In the context of Kafka, "bindings" refer to the connections between Kafka and other systems or applications. There are several levels of bindings as described below: @@ -21,7 +23,8 @@ In the context of Kafka, "bindings" refer to the connections between Kafka and o - Channel Bindings - Operation Bindings -**How binding works in Kafka** +**How binding works with Kafka** + You must understand some essential parts of the process to understand how binding works. Kafka as a messaging system - Think of Kafka as a courier service - A messaging system that handles sending and receiving messages between applications. @@ -38,18 +41,40 @@ Bindings: Bindings are relevant when integrating Kafka with other programs or se Bindings are important because they indicate how Kafka components are configured. - +The diagram below shows how bindings with Kafka works. + +```mermaid +graph LR + A[Producer] -->|Sends Messages| B[Kafka Topic] + B -->|Bindings| C{Kafka Broker} + C -->|Delivers Messages| D[Consumer 1] + C -->|Delivers Messages| E[Consumer 2] + C -->|Delivers Messages| F[Consumer N] + + style B fill:#f9f,stroke:#333,stroke-width:2px + style C fill:#fc6,stroke:#333,stroke-width:2px +``` + +In the diagram above; + +- The **producer** represents the system or service that transmits messages to Kafka. + +- **Kafka Topic**: The name of the category or feed where messages are stored. + +- **Bindings**: The connection or configuration between Kafka topics and the broker. + +- **Kafka Broker**: The central node in charge of message distribution. + +- **Consumer 1, 2, N**: Various systems or services that receive Kafka messages. Now, let’s see how to use bindings with Kafka. ## Installation Guide From a8020e0a96de534503cdbcde9f084c98f9338c40 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Wed, 22 Nov 2023 18:51:45 +0100 Subject: [PATCH 04/39] Rewrote the document --- pages/docs/tutorials/bindings-with-kafka.md | 83 ------------------- pages/docs/tutorials/kafka/_section.md | 4 + .../tutorials/kafka/bindings-with-kafka.md | 38 +++++++++ pages/docs/tutorials/kafka/index.md | 4 + 4 files changed, 46 insertions(+), 83 deletions(-) delete mode 100644 pages/docs/tutorials/bindings-with-kafka.md create mode 100644 pages/docs/tutorials/kafka/_section.md create mode 100644 pages/docs/tutorials/kafka/bindings-with-kafka.md create mode 100644 pages/docs/tutorials/kafka/index.md diff --git a/pages/docs/tutorials/bindings-with-kafka.md b/pages/docs/tutorials/bindings-with-kafka.md deleted file mode 100644 index 2fb7b520f537..000000000000 --- a/pages/docs/tutorials/bindings-with-kafka.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Bindings with Kafka -description: In this tutorial, you'll learn how bindings with Kafka works and different ways to utilize bindings -weight: 150 ---- - -## Introduction - -In this tutorial, you will learn how bindings with Kafka works. You will learn how to extend your AsyncAPI document with Protocol-specific information, such as how to specify kafka topic-specific configurations or how to define kafka message key content. - -## Background Context - -**What is Kafka** - -Kafka is a messaging system that allows for the efficient handling and processing of data streams. - -**What is binding?** - -In the context of Kafka, "bindings" refer to the connections between Kafka and other systems or applications. There are several levels of bindings as described below: - - -- Server Bindings -- Channel Bindings -- Operation Bindings - -**How binding works with Kafka** - -You must understand some essential parts of the process to understand how binding works. - -Kafka as a messaging system - Think of Kafka as a courier service - A messaging system that handles sending and receiving messages between applications. - -Producers and Consumers - Producers send packages (messages) to the courier service (Kafka), and consumers receive these packages. - -Topics: Kafka organizes messages into categories. Just like a courier service, it will group items based on several cases, like how heavy the package is or the arrival date. It’s like having different boxes for different messages. - -Bindings: Bindings are relevant when integrating Kafka with other programs or services. A binding is a specific agreement or configuration that governs how an application connects to and interacts with Kafka. It can include information such as: - -- Which topics should an application read from or write to? -- How should messages be formatted? -- What are the rules for interacting with various forms of data or messages? - -Bindings are important because they indicate how Kafka components are configured. - -The diagram below shows how bindings with Kafka works. - -```mermaid -graph LR - A[Producer] -->|Sends Messages| B[Kafka Topic] - B -->|Bindings| C{Kafka Broker} - C -->|Delivers Messages| D[Consumer 1] - C -->|Delivers Messages| E[Consumer 2] - C -->|Delivers Messages| F[Consumer N] - - style B fill:#f9f,stroke:#333,stroke-width:2px - style C fill:#fc6,stroke:#333,stroke-width:2px -``` - -In the diagram above; - -- The **producer** represents the system or service that transmits messages to Kafka. - -- **Kafka Topic**: The name of the category or feed where messages are stored. - -- **Bindings**: The connection or configuration between Kafka topics and the broker. - -- **Kafka Broker**: The central node in charge of message distribution. - -- **Consumer 1, 2, N**: Various systems or services that receive Kafka messages. - -Now, let’s see how to use bindings with Kafka. - -## Installation Guide - - - - -## Summary -## Next Steps - diff --git a/pages/docs/tutorials/kafka/_section.md b/pages/docs/tutorials/kafka/_section.md new file mode 100644 index 000000000000..994e7b8144ac --- /dev/null +++ b/pages/docs/tutorials/kafka/_section.md @@ -0,0 +1,4 @@ +--- +title: 'Kafka' +weight: 2 +--- \ No newline at end of file diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md new file mode 100644 index 000000000000..048e6060743c --- /dev/null +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -0,0 +1,38 @@ +--- +title: Adding Kafka information using bindings. +description: In this tutorial, you'll learn how bindings with Kafka work and different ways to utilize bindings in your AsyncAPI applications. +weight: 150 +--- + +## Introduction + +In this tutorial, you will learn how bindings with Kafka works. You will learn how to extend your AsyncAPI document with Protocol-specific information, such as how to specify Kafka topic-specific configurations or how to define Kafka message key content. + +## Background Context +Bindings are relevant when integrating Kafka with other programs or services. A binding is a specific agreement or configuration that governs how an application connects to and interacts with Kafka. It can include information such as: + +- Which topics should an application read from or write to? +- How should messages be formatted? +- What are the rules for interacting with various data or messages? + +Bindings configure ecosystems to accommodate Kafka-specific functionalities not supported by AsyncAPI's core features. This necessity for bindings arises to bridge these specific requirements of Kafka with AsyncAPI. Hence the need for bindings. + +You can configure several objects using Kafka bindings. However, for the scope of this tutorial, we are focusing on two levels of bindings: + +- Server Bindings +- Channel Bindings + + +The diagram below shows how bindings with Kafka work. + + + +Now, let's see how to use bindings with Kafka. + + +## Summary + +In this tutorial, you learned how to configure server and channel bindings. You also learned that Kafka bindings are essential because they indicate how Kafka components are configured. + +## Next Steps + diff --git a/pages/docs/tutorials/kafka/index.md b/pages/docs/tutorials/kafka/index.md new file mode 100644 index 000000000000..e204dbc49ce4 --- /dev/null +++ b/pages/docs/tutorials/kafka/index.md @@ -0,0 +1,4 @@ +--- +title: Tutorial-1 +weight: 20 +--- \ No newline at end of file From a4217aa9f5d41a69fe3d95c8b73b72e255d3cc47 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Wed, 29 Nov 2023 17:44:02 +0100 Subject: [PATCH 05/39] implemented chnages and feedback --- .../tutorials/kafka/bindings-with-kafka.md | 27 ++++++++++--------- pages/docs/tutorials/kafka/index.md | 2 +- 2 files changed, 15 insertions(+), 14 deletions(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 048e6060743c..eb65d1152b6a 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -6,33 +6,34 @@ weight: 150 ## Introduction -In this tutorial, you will learn how bindings with Kafka works. You will learn how to extend your AsyncAPI document with Protocol-specific information, such as how to specify Kafka topic-specific configurations or how to define Kafka message key content. +In this tutorial, you will learn how bindings with Kafka works. You will learn how to define Kafka message key content and extend your AsyncAPI document with protocol-specific information. ## Background Context -Bindings are relevant when integrating Kafka with other programs or services. A binding is a specific agreement or configuration that governs how an application connects to and interacts with Kafka. It can include information such as: -- Which topics should an application read from or write to? -- How should messages be formatted? -- What are the rules for interacting with various data or messages? +Bindings are relevant when integrating Kafka with other programs or services. A binding is a specific agreement or configuration that governs how an application connects to and interacts with Kafka. It includes information such as, topics an application reads from or writes to, how the messages are formatted, and the rules for interacting with various data or messages. Bindings configure ecosystems to accommodate Kafka-specific functionalities not supported by AsyncAPI's core features. This necessity for bindings arises to bridge these specific requirements of Kafka with AsyncAPI. Hence the need for bindings. -You can configure several objects using Kafka bindings. However, for the scope of this tutorial, we are focusing on two levels of bindings: - -- Server Bindings -- Channel Bindings - +You can configure several objects using Kafka bindings. However, for the scope of this tutorial, we are focusing on two levels of bindings: [server bindings](https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object) and [channel bindings](https://github.com/asyncapi/bindings/tree/master/kafka#channel-binding-object). The diagram below shows how bindings with Kafka work. +```mermaid +sequenceDiagram + A[Kafka Broker/Cluster] -->|Kafka bindings| B[receivers] + C[senders] -->|message flow| A - -Now, let's see how to use bindings with Kafka. + style A fill:#f9f,stroke:#333,stroke-width:2px + style B fill:#ccf,stroke:#333,stroke-width:2px + style C fill:#cfc,stroke:#333,stroke-width:2px + %% style D fill:#cfc,stroke:#333,stroke-width:2px +``` ## Summary -In this tutorial, you learned how to configure server and channel bindings. You also learned that Kafka bindings are essential because they indicate how Kafka components are configured. +In this tutorial, you learned how to configure server and channel bindings. You also learned that Kafka bindings are essential in integrating Kafka with different systems, platforms, or protocols, especially in API specifications like AsyncAPI. + ## Next Steps diff --git a/pages/docs/tutorials/kafka/index.md b/pages/docs/tutorials/kafka/index.md index e204dbc49ce4..6d33c714e63e 100644 --- a/pages/docs/tutorials/kafka/index.md +++ b/pages/docs/tutorials/kafka/index.md @@ -1,4 +1,4 @@ --- -title: Tutorial-1 +title: Kafka Tutorial weight: 20 --- \ No newline at end of file From 60510bf3082ad0ad3d810d1ab6dba871de96270a Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Wed, 6 Dec 2023 07:05:55 +0100 Subject: [PATCH 06/39] Updated docs --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index eb65d1152b6a..3eb1f5a30e66 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -1,16 +1,16 @@ --- title: Adding Kafka information using bindings. description: In this tutorial, you'll learn how bindings with Kafka work and different ways to utilize bindings in your AsyncAPI applications. -weight: 150 +weight: 60 --- ## Introduction -In this tutorial, you will learn how bindings with Kafka works. You will learn how to define Kafka message key content and extend your AsyncAPI document with protocol-specific information. +In the previous tutorial, you learnt how to manage schemas with schema registry. In this tutorial, you will learn how bindings with Kafka works. You will learn how to define Kafka message key content and extend your AsyncAPI document with protocol-specific information. ## Background Context -Bindings are relevant when integrating Kafka with other programs or services. A binding is a specific agreement or configuration that governs how an application connects to and interacts with Kafka. It includes information such as, topics an application reads from or writes to, how the messages are formatted, and the rules for interacting with various data or messages. +Bindings are relevant when integrating Kafka with other programs or services. A binding is a specific agreement or configuration that governs how an application connects to and interacts with Kafka. It includes information such as topics an application reads from or writes to, how the messages are formatted, and the rules for interacting with various data or messages. Bindings are important because they show indications about how you can configure Kafka components. Bindings configure ecosystems to accommodate Kafka-specific functionalities not supported by AsyncAPI's core features. This necessity for bindings arises to bridge these specific requirements of Kafka with AsyncAPI. Hence the need for bindings. @@ -29,6 +29,9 @@ sequenceDiagram %% style D fill:#cfc,stroke:#333,stroke-width:2px ``` +## Server Bindings + +## Channel Bindings ## Summary @@ -37,3 +40,4 @@ In this tutorial, you learned how to configure server and channel bindings. You ## Next Steps +Now that you have completed this tutorial, you can [learn more about other Kakfa bindings.](https://github.com/asyncapi/bindings/tree/master/kafka) From efcd3973463f1a38b463e8bd7d8d71fa12af2a78 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Wed, 6 Dec 2023 08:46:42 +0100 Subject: [PATCH 07/39] Made changes based on feedback received --- .../tutorials/kafka/bindings-with-kafka.md | 29 +++++++++---------- 1 file changed, 13 insertions(+), 16 deletions(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 3eb1f5a30e66..6b83ffddc48a 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -1,43 +1,40 @@ --- title: Adding Kafka information using bindings. -description: In this tutorial, you'll learn how bindings with Kafka work and different ways to utilize bindings in your AsyncAPI applications. -weight: 60 +description: In this tutorial, you'll learn how how to add specific bindings to AsyncAPI document. --- ## Introduction -In the previous tutorial, you learnt how to manage schemas with schema registry. In this tutorial, you will learn how bindings with Kafka works. You will learn how to define Kafka message key content and extend your AsyncAPI document with protocol-specific information. +In a previous tutorial, you learnt how to manage schemas with schema registry. In this tutorial, you will learn how bindings with Kafka works. You will learn how to define Kafka message key content and extend your AsyncAPI document with protocol-specific information. ## Background Context -Bindings are relevant when integrating Kafka with other programs or services. A binding is a specific agreement or configuration that governs how an application connects to and interacts with Kafka. It includes information such as topics an application reads from or writes to, how the messages are formatted, and the rules for interacting with various data or messages. Bindings are important because they show indications about how you can configure Kafka components. +Bindings enhances AsyncAPI documentation by providing protocol-specific information. They append to different document sections, such as servers, channels, or messages, and they include standard information that is unique to a particular protocol. -Bindings configure ecosystems to accommodate Kafka-specific functionalities not supported by AsyncAPI's core features. This necessity for bindings arises to bridge these specific requirements of Kafka with AsyncAPI. Hence the need for bindings. +Bindings improve the understanding and usability of the API by offering more setup options and context for various protocols. It includes information such as topics an application reads from or writes to, how the messages are formatted, and the rules for interacting with various data or messages. + +Bindings configure ecosystems to accommodate specific functionalities not supported by AsyncAPI's core features. You can configure several objects using Kafka bindings. However, for the scope of this tutorial, we are focusing on two levels of bindings: [server bindings](https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object) and [channel bindings](https://github.com/asyncapi/bindings/tree/master/kafka#channel-binding-object). + The diagram below shows how bindings with Kafka work. -```mermaid -sequenceDiagram - A[Kafka Broker/Cluster] -->|Kafka bindings| B[receivers] - C[senders] -->|message flow| A - style A fill:#f9f,stroke:#333,stroke-width:2px - style B fill:#ccf,stroke:#333,stroke-width:2px - style C fill:#cfc,stroke:#333,stroke-width:2px - %% style D fill:#cfc,stroke:#333,stroke-width:2px -``` ## Server Bindings +Server bindings provide protocol-specific configuration details for connecting and interacting with a server. + ## Channel Bindings +Channel bindings provide protocol-specific information for a particular channel. For example, in Kafka, you can specify number of partitions or replicas for a given topic. + ## Summary -In this tutorial, you learned how to configure server and channel bindings. You also learned that Kafka bindings are essential in integrating Kafka with different systems, platforms, or protocols, especially in API specifications like AsyncAPI. +In this tutorial, you learned how to configure server and channel bindings. You also learned that bindings are essential in integrating Kafka with different systems, platforms, or protocols, especially in API specifications like AsyncAPI. ## Next Steps -Now that you have completed this tutorial, you can [learn more about other Kakfa bindings.](https://github.com/asyncapi/bindings/tree/master/kafka) +Now that you have completed this tutorial, you can [learn more about other Kakfa bindings](https://github.com/asyncapi/bindings/tree/master/kafka) or [protocol-specific bindings](https://github.com/asyncapi/bindings). From 5cd1ac66b344796a5d1733bdaee80cacbcfbd734 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Wed, 6 Dec 2023 16:01:24 +0100 Subject: [PATCH 08/39] Added a new version for diagram --- .../docs/tutorials/kafka/bindings-with-kafka.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 6b83ffddc48a..eaad79b9993d 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -5,7 +5,7 @@ description: In this tutorial, you'll learn how how to add specific bindings to ## Introduction -In a previous tutorial, you learnt how to manage schemas with schema registry. In this tutorial, you will learn how bindings with Kafka works. You will learn how to define Kafka message key content and extend your AsyncAPI document with protocol-specific information. +In a previous tutorial, you learnt how to manage schemas with schema registry. In this tutorial, you will learn how bindings with Kafka works by defining Kafka message key content and extending your AsyncAPI document with protocol-specific information. ## Background Context @@ -20,7 +20,20 @@ You can configure several objects using Kafka bindings. However, for the scope o The diagram below shows how bindings with Kafka work. - +```mermaid +graph TD + A[AsyncAPI Application] -->|Kafka Server Bindings| B[Kafka Broker/Cluster] + B -->|Kafka Channel Bindings| C[Producer Channel] + B -->|Kafka Channel Bindings| D[Consumer Channel] + C -->|Kafka Message Bindings| E[Producer Message] + D -->|Kafka Message Bindings| F[Consumer Message] + style A fill:#f9f,stroke:#333,stroke-width:4px + style B fill:#ccf,stroke:#333,stroke-width:4px + style C fill:#fcf,stroke:#333,stroke-width:4px + style D fill:#fcf,stroke:#333,stroke-width:4px + style E fill:#cff,stroke:#333,stroke-width:4px + style F fill:#cff,stroke:#333,stroke-width:4px +``` ## Server Bindings From f3faba094b29c5baed5b34af1361d70ced4e4832 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Wed, 6 Dec 2023 16:18:18 +0100 Subject: [PATCH 09/39] Updated the title to make it brief --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index eaad79b9993d..611f9e8cf00c 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -1,6 +1,6 @@ --- -title: Adding Kafka information using bindings. -description: In this tutorial, you'll learn how how to add specific bindings to AsyncAPI document. +title: Kafka-specific Bindings +description: In this tutorial, you'll learn how how to add specific Kafka information to an AsyncAPI document using bindings. --- ## Introduction From bee114504186999681a5344f20e1cccce7878f28 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Wed, 6 Dec 2023 17:00:19 +0100 Subject: [PATCH 10/39] updated based on feedback --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 611f9e8cf00c..0ae5d5e8f282 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -13,7 +13,7 @@ Bindings enhances AsyncAPI documentation by providing protocol-specific informat Bindings improve the understanding and usability of the API by offering more setup options and context for various protocols. It includes information such as topics an application reads from or writes to, how the messages are formatted, and the rules for interacting with various data or messages. -Bindings configure ecosystems to accommodate specific functionalities not supported by AsyncAPI's core features. +Bindings definitions allow you to specify the protocol specific functionalities not supported by AsyncAPI's core features. You can configure several objects using Kafka bindings. However, for the scope of this tutorial, we are focusing on two levels of bindings: [server bindings](https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object) and [channel bindings](https://github.com/asyncapi/bindings/tree/master/kafka#channel-binding-object). From 7edaf18cf1e078f774b8e0b18fbd3ae20eeff8a5 Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Wed, 6 Dec 2023 08:35:53 -0800 Subject: [PATCH 11/39] Apply suggestions from code review --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 0ae5d5e8f282..d886c75791c5 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -9,11 +9,11 @@ In a previous tutorial, you learnt how to manage schemas with schema registry. I ## Background Context -Bindings enhances AsyncAPI documentation by providing protocol-specific information. They append to different document sections, such as servers, channels, or messages, and they include standard information that is unique to a particular protocol. +Bindings provide protocol-specific information for your Event-Driven application. Protocols have specific ways of handling messages, and bindings abstract these details away from your application's core logic. Bindings improve the understanding and usability of the API by offering more setup options and context for various protocols. It includes information such as topics an application reads from or writes to, how the messages are formatted, and the rules for interacting with various data or messages. + +In an AsyncAPI document, bindings can be appended to different document sections, such as servers, channels, or messages. They include standard information that is unique to a particular protocol. Bindings definitions allow you to specify the protocol-specific functionalities not supported by AsyncAPI's core features. -Bindings improve the understanding and usability of the API by offering more setup options and context for various protocols. It includes information such as topics an application reads from or writes to, how the messages are formatted, and the rules for interacting with various data or messages. -Bindings definitions allow you to specify the protocol specific functionalities not supported by AsyncAPI's core features. You can configure several objects using Kafka bindings. However, for the scope of this tutorial, we are focusing on two levels of bindings: [server bindings](https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object) and [channel bindings](https://github.com/asyncapi/bindings/tree/master/kafka#channel-binding-object). From cc4bcb1e2928cb373827e12b178dffb1fd04cd6e Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Wed, 6 Dec 2023 17:43:56 +0100 Subject: [PATCH 12/39] Updated --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 0ae5d5e8f282..f6f088d63dca 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -5,7 +5,7 @@ description: In this tutorial, you'll learn how how to add specific Kafka inform ## Introduction -In a previous tutorial, you learnt how to manage schemas with schema registry. In this tutorial, you will learn how bindings with Kafka works by defining Kafka message key content and extending your AsyncAPI document with protocol-specific information. +In a previous tutorial, you learnt how to manage schemas with schema registry. In this tutorial, you will learn how bindings with Kafka work by defining Kafka message key content and extending your AsyncAPI document with protocol-specific information. ## Background Context From c6746db0456823e42ba092766e756eda411b1363 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Tue, 12 Dec 2023 07:13:16 +0100 Subject: [PATCH 13/39] Updated background context --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 63c9ca477833..eff98587fb95 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -9,7 +9,7 @@ In a previous tutorial, you learnt how to manage schemas with schema registry. I ## Background Context -Bindings provide protocol-specific information for your Event-Driven application. Protocols have specific ways of handling messages; bindings abstract these details away from your application's core logic. Bindings improve the understanding and usability of the API by offering more setup options and context for various protocols. It includes information such as topics an application reads from or writes to, how the messages are formatted, and the rules for interacting with multiple data or messages. +Bindings are crucial to an Event-driven application as they provide protocol-specific information that abstracts the details of how protocols handle messages from the core logic of your application. Bindings improve the understanding and usability of the API by offering more setup options and context for various protocols. It includes information such as topics an application reads from or writes to, how the messages are formatted, and the rules for interacting with multiple data or messages. In an AsyncAPI document, bindings can be appended to different document sections, such as servers, channels, or messages. They include standard information that is unique to a particular protocol. Bindings definitions allow you to specify the protocol-specific functionalities not supported by AsyncAPI's core features. From 60172ce9c037c3dc9203ab16e37fcf1354edce30 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Thu, 11 Jan 2024 17:40:42 +0100 Subject: [PATCH 14/39] Updated changes --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index eff98587fb95..d2da4ba5d115 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -16,18 +16,6 @@ In an AsyncAPI document, bindings can be appended to different document sections You can configure several objects using Kafka bindings. However, for the scope of this tutorial, we are focusing on three levels of bindings: [server bindings](https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object), [channel bindings](https://github.com/asyncapi/bindings/tree/master/kafka#channel-binding-object) and [message bindings](https://github.com/asyncapi/bindings/tree/master/kafka#message-binding-object). -The diagram below shows how bindings with Kafka work. - -```mermaid -graph TD - A[AsyncAPI Application] -->|Kafka Server Bindings| B[Kafka Broker] - B -->|Kafka Channel Bindings| C[Producer Channel] - B -->|Kafka Channel Bindings| D[Consumer Channel] - C -->|Kafka Message Bindings| E[Producer Message] - D -->|Kafka Message Bindings| F[Consumer Message] - style A fill:#47BCEE,stroke:#333,stroke-width:4px -``` - ## Add server bindings Server bindings provide protocol-specific configuration details for connecting and interacting with a server. From 8a8ea806386facb9cc589be39c82e05ba337c0b9 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Thu, 25 Jan 2024 09:40:46 +0100 Subject: [PATCH 15/39] Removed index and section md --- pages/docs/tutorials/kafka/_section.md | 4 ---- pages/docs/tutorials/kafka/index.md | 4 ---- 2 files changed, 8 deletions(-) delete mode 100644 pages/docs/tutorials/kafka/_section.md delete mode 100644 pages/docs/tutorials/kafka/index.md diff --git a/pages/docs/tutorials/kafka/_section.md b/pages/docs/tutorials/kafka/_section.md deleted file mode 100644 index 994e7b8144ac..000000000000 --- a/pages/docs/tutorials/kafka/_section.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Kafka' -weight: 2 ---- \ No newline at end of file diff --git a/pages/docs/tutorials/kafka/index.md b/pages/docs/tutorials/kafka/index.md deleted file mode 100644 index 6d33c714e63e..000000000000 --- a/pages/docs/tutorials/kafka/index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Kafka Tutorial -weight: 20 ---- \ No newline at end of file From bc630a8fabe89c9c00877ae67e4c554909f61b5a Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Wed, 7 Feb 2024 12:00:26 +0100 Subject: [PATCH 16/39] added code snippets from previous tutorial step --- .../tutorials/kafka/bindings-with-kafka.md | 61 ++++++++++++++++++- 1 file changed, 59 insertions(+), 2 deletions(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index d2da4ba5d115..25087f6de91c 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -15,18 +15,75 @@ In an AsyncAPI document, bindings can be appended to different document sections You can configure several objects using Kafka bindings. However, for the scope of this tutorial, we are focusing on three levels of bindings: [server bindings](https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object), [channel bindings](https://github.com/asyncapi/bindings/tree/master/kafka#channel-binding-object) and [message bindings](https://github.com/asyncapi/bindings/tree/master/kafka#message-binding-object). +Using the code snippets from the previous tutorial, where you learned [how to manage Avro schemas using a centralized schema registry that enables you to share schemas across multiple applications](pages/docs/tutorials/kafka/managing-schemas-using-schema-registry.md), you will add configurations for server, channel, and message bindings. ## Add server bindings -Server bindings provide protocol-specific configuration details for connecting and interacting with a server. +Server bindings provide protocol-specific configuration details for connecting and interacting with a server. For server bindings, we will add three fields to configure the server bindings. + +``` +servers: + kafkaServer: + host: test.mykafkacluster.org:8092 + description: Kafka Server + protocol: kafka + production: + bindings: + kafka: + schemaRegistryUrl: '$ref: http://localhost:8080/apis/registry/v2/groups/my-group/artifacts/UserSignedUp' + schemaRegistryVendor: 'apicurio' + bindingVersion: '0.4.0' +``` ## Add channel bindings Channel bindings provide protocol-specific information for a particular channel. For example, in Kafka, you can specify number of partitions or replicas for a given topic. + +``` +channels: + userSignedUp: + description: This channel contains a message per each user who signs up in our application. + address: user_signedup + messages: + userSignedUp: + $ref: '#/components/messages/userSignedUp' + bindings: + kafka: + topic: 'UserSignedUp' + partitions: 10 + replicas: 2 + topicConfiguration: + cleanup.policy: ["delete", "compact"] + retention.ms: 604800000 + retention.bytes: 1000000000 + delete.retention.ms: 86400000 + max.message.bytes: 1048588 + bindingVersion: '0.4.0' +``` + + ## Add message bindings -Message bindings provide protocol-specific information for a specific message. Like the Kafka topic it's associated with, message key (if any), and Kafka-specific properties. +Message bindings provide protocol-specific information for a specific message. Like the Kafka topic it's associated with, message key (if any), and Kafka-specific properties. + +``` +components: + messages: + userSignedUp: + bindings: + kafka: + key: + type: string + enum: ['myKey'] + schemaIdLocation: 'payload' + schemaIdPayloadEncoding: '4' + bindingVersion: '0.4.0' + payload: + schemaFormat: 'application/vnd.apache.avro+json;version=1.9.0' + schema: + $ref: http://localhost:8080/apis/registry/v2/groups/my-group/artifacts/UserSignedUp +``` ## Summary From 29383e98147a44ab0372733f4b4e561432fc60d3 Mon Sep 17 00:00:00 2001 From: Quetzalli Date: Fri, 9 Feb 2024 19:25:53 -0800 Subject: [PATCH 17/39] editorial rewrite --- .../tutorials/kafka/bindings-with-kafka.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 25087f6de91c..0d0eab112b36 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -1,25 +1,25 @@ --- -title: Kafka-specific Bindings -description: In this tutorial, you'll learn how how to add specific Kafka information to an AsyncAPI document using bindings. +title: Kafka specific bindings +description: Learn how to configure Kafka bindings in your AsyncAPI document. --- ## Introduction -In a previous tutorial, you learnt how to manage schemas with schema registry. In this tutorial, you will learn how bindings with Kafka work by defining Kafka message key content and extending your AsyncAPI document with protocol-specific information. +In a previous tutorial, you learned how to manage schemas with a schema registry. This tutorial teaches you how Kafka bindings function by defining Kafka messages and expanding your AsyncAPI document with protocol-specific details. -## Background Context +## Background context -Bindings are crucial to an Event-driven application as they provide protocol-specific information that abstracts the details of how protocols handle messages from the core logic of your application. Bindings improve the understanding and usability of the API by offering more setup options and context for various protocols. It includes information such as topics an application reads from or writes to, how the messages are formatted, and the rules for interacting with multiple data or messages. +Bindings are essential for event-driven applications because they provide protocol-specific details, abstracting the complexities of message handling from your application's core logic. They enhance the API's clarity and usability by offering setup options and context for different protocols. Bindings include details like the topics your application reads from or writes to, message formatting, and rules for interacting with multiple data or messages. -In an AsyncAPI document, bindings can be appended to different document sections, such as servers, channels, or messages. They include standard information that is unique to a particular protocol. Bindings definitions allow you to specify the protocol-specific functionalities not supported by AsyncAPI's core features. +In an AsyncAPI document, bindings can be added to various sections like servers, channels, or messages. They contain protocol-specific details unique to each protocol. Binding definitions let you specify functionalities specific to the protocol, which are not covered by AsyncAPI's core features. -You can configure several objects using Kafka bindings. However, for the scope of this tutorial, we are focusing on three levels of bindings: [server bindings](https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object), [channel bindings](https://github.com/asyncapi/bindings/tree/master/kafka#channel-binding-object) and [message bindings](https://github.com/asyncapi/bindings/tree/master/kafka#message-binding-object). +You can configure several objects using Kafka bindings. However, for the scope of this tutorial, you will focus on three levels of bindings: [server bindings](https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object), [channel bindings](https://github.com/asyncapi/bindings/tree/master/kafka#channel-binding-object) and [message bindings](https://github.com/asyncapi/bindings/tree/master/kafka#message-binding-object). -Using the code snippets from the previous tutorial, where you learned [how to manage Avro schemas using a centralized schema registry that enables you to share schemas across multiple applications](pages/docs/tutorials/kafka/managing-schemas-using-schema-registry.md), you will add configurations for server, channel, and message bindings. +Using the code snippets from the previous tutorial, where you learned [how to manage Avro schemas using a centralized schema registry that enables you to share schemas across multiple applications](pages/docs/tutorials/kafka/managing-schemas-using-schema-registry), you will add configurations for server, channel, and message bindings. ## Add server bindings -Server bindings provide protocol-specific configuration details for connecting and interacting with a server. For server bindings, we will add three fields to configure the server bindings. +Server bindings provide protocol-specific configuration details for connecting and interacting with a server. For server bindings, we will add three fields: ``` servers: @@ -37,7 +37,7 @@ servers: ## Add channel bindings -Channel bindings provide protocol-specific information for a particular channel. For example, in Kafka, you can specify number of partitions or replicas for a given topic. +Channel bindings provide protocol-specific information for a particular channel. In Kafka, you can specify a given topic's number of partitions or replicas. ``` @@ -65,7 +65,7 @@ channels: ## Add message bindings -Message bindings provide protocol-specific information for a specific message. Like the Kafka topic it's associated with, message key (if any), and Kafka-specific properties. +Message bindings provide protocol-specific information for a specific message. Like the Kafka topic, it's associated with a message key (if any) and Kafka-specific properties. ``` components: @@ -87,9 +87,9 @@ components: ## Summary -In this tutorial, you learned how to configure server and channel bindings. You also learned that bindings are essential in integrating Kafka with different systems, platforms, or protocols, especially in API specifications like AsyncAPI. +In this tutorial, you learned how to configure server and channel bindings. You also learned that bindings are essential when integrating Kafka with different systems, platforms, or protocols — especially in API specifications like AsyncAPI. -## Next Steps +## Next steps Now that you have completed this tutorial, you can [learn more about other Kakfa bindings](https://github.com/asyncapi/bindings/tree/master/kafka) or [protocol-specific bindings](https://github.com/asyncapi/bindings). From 3e201f29a6fc87640777f71479782317c5a28358 Mon Sep 17 00:00:00 2001 From: Quetzalli Date: Fri, 9 Feb 2024 19:26:17 -0800 Subject: [PATCH 18/39] Update pages/docs/tutorials/kafka/bindings-with-kafka.md --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 0d0eab112b36..9294e3c0d59e 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -1,5 +1,5 @@ --- -title: Kafka specific bindings +title: Kafka bindings description: Learn how to configure Kafka bindings in your AsyncAPI document. --- From abba6f8c5175fdb6494373903537b423884921e8 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Mon, 12 Feb 2024 14:14:10 +0100 Subject: [PATCH 19/39] Added metadata for page weight --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 1 + 1 file changed, 1 insertion(+) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 9294e3c0d59e..ccfc29c58bf3 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -1,6 +1,7 @@ --- title: Kafka bindings description: Learn how to configure Kafka bindings in your AsyncAPI document. +weight: 300 --- ## Introduction From 98d0cdb61f2f79ef9f40ae4e18437d622d10e1f2 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Mon, 19 Feb 2024 06:09:22 +0100 Subject: [PATCH 20/39] Update pages/docs/tutorials/kafka/bindings-with-kafka.md the url must be the base path of the registry api the $ref must referencing a component or an external file, so this is not appropriate here. Co-authored-by: Ludovic Dussart --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index ccfc29c58bf3..6c43c8cd5695 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -31,7 +31,7 @@ servers: production: bindings: kafka: - schemaRegistryUrl: '$ref: http://localhost:8080/apis/registry/v2/groups/my-group/artifacts/UserSignedUp' + schemaRegistryUrl: 'http://localhost:8080/apis/registry/' schemaRegistryVendor: 'apicurio' bindingVersion: '0.4.0' ``` From a33769a6e7b0369c6d9e514ec98bc567f6d4d231 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Sat, 24 Feb 2024 11:02:26 +0100 Subject: [PATCH 21/39] Updated document based on feedback on PR --- .../tutorials/kafka/bindings-with-kafka.md | 110 ++++++++++++++++-- 1 file changed, 99 insertions(+), 11 deletions(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 6c43c8cd5695..ebfb59953ff1 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -14,15 +14,15 @@ Bindings are essential for event-driven applications because they provide protoc In an AsyncAPI document, bindings can be added to various sections like servers, channels, or messages. They contain protocol-specific details unique to each protocol. Binding definitions let you specify functionalities specific to the protocol, which are not covered by AsyncAPI's core features. -You can configure several objects using Kafka bindings. However, for the scope of this tutorial, you will focus on three levels of bindings: [server bindings](https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object), [channel bindings](https://github.com/asyncapi/bindings/tree/master/kafka#channel-binding-object) and [message bindings](https://github.com/asyncapi/bindings/tree/master/kafka#message-binding-object). +You can configure several objects using Kafka bindings. However, for the scope of this tutorial, you will focus on four levels of bindings: [server bindings](https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object), [operations binding](https://github.com/asyncapi/bindings/tree/master/kafka#operation-binding-object), [channel bindings](https://github.com/asyncapi/bindings/tree/master/kafka#channel-binding-object) and [message bindings](https://github.com/asyncapi/bindings/tree/master/kafka#message-binding-object). -Using the code snippets from the previous tutorial, where you learned [how to manage Avro schemas using a centralized schema registry that enables you to share schemas across multiple applications](pages/docs/tutorials/kafka/managing-schemas-using-schema-registry), you will add configurations for server, channel, and message bindings. +Using the code snippets from the previous tutorial, where you learned [how to manage Avro schemas using a centralized schema registry that enables you to share schemas across multiple applications](pages/docs/tutorials/kafka/managing-schemas-using-schema-registry), you will add configurations for server, operations, channel, and message bindings. ## Add server bindings Server bindings provide protocol-specific configuration details for connecting and interacting with a server. For server bindings, we will add three fields: -``` +```yaml servers: kafkaServer: host: test.mykafkacluster.org:8092 @@ -33,15 +33,37 @@ servers: kafka: schemaRegistryUrl: 'http://localhost:8080/apis/registry/' schemaRegistryVendor: 'apicurio' - bindingVersion: '0.4.0' + bindingVersion: '0.5.0' ``` -## Add channel bindings +> Important: `Binding-version` is the field version of a binding. If omitted, the "latest" version MUST be assumed. The `bindingversion` field is an optional field that is available for all bindings. -Channel bindings provide protocol-specific information for a particular channel. In Kafka, you can specify a given topic's number of partitions or replicas. +## Add operation bindings + +Operation bindings object contains information about the operation representation in Kafka (eg. the way to consume messages). +```yaml +operations: + onUserSignedUp: + action: receive + channel: + $ref: '#/channels/userSignedUp' + bindings: + kafka: + groupId: + type: string + enum: ['myGroupId'] + clientId: + type: string + enum: ['myClientId'] ``` + +## Add channel bindings + +Channel bindings provide protocol-specific information for a particular channel. In Kafka, you can specify a given topic's number of partitions or replicas. + +```yaml channels: userSignedUp: description: This channel contains a message per each user who signs up in our application. @@ -60,15 +82,13 @@ channels: retention.bytes: 1000000000 delete.retention.ms: 86400000 max.message.bytes: 1048588 - bindingVersion: '0.4.0' ``` - ## Add message bindings Message bindings provide protocol-specific information for a specific message. Like the Kafka topic, it's associated with a message key (if any) and Kafka-specific properties. -``` +```yaml components: messages: userSignedUp: @@ -78,14 +98,82 @@ components: type: string enum: ['myKey'] schemaIdLocation: 'payload' - schemaIdPayloadEncoding: '4' - bindingVersion: '0.4.0' + schemaIdPayloadEncoding: 'apicurio-new' + schemaLookupStrategy: 'TopicIdStrategy' + bindingVersion: '0.5.0' payload: schemaFormat: 'application/vnd.apache.avro+json;version=1.9.0' schema: $ref: http://localhost:8080/apis/registry/v2/groups/my-group/artifacts/UserSignedUp ``` +Congratulations, you've completed the tutorial! Putting these blocks together gives you an AsyncAPI document all ready to go. + +```yaml +asyncapi: 3.0.0 +info: + title: User Signup API + version: 1.0.0 + description: The API notifies you whenever a new user signs up in the application. +servers: + kafkaServer: + host: test.mykafkacluster.org:8092 + description: Kafka Server + protocol: kafka + production: + bindings: + kafka: + schemaRegistryUrl: 'http://localhost:8080/apis/registry/' + schemaRegistryVendor: 'apicurio' + bindingVersion: '0.5.0' +operations: + onUserSignedUp: + action: receive + channel: + $ref: '#/channels/userSignedUp' + bindings: + kafka: + groupId: + type: string + enum: ['myGroupId'] + clientId: + type: string + enum: ['myClientId'] +channels: + userSignedUp: + description: This channel contains a message per each user who signs up in our application. + address: user_signedup + messages: + userSignedUp: + $ref: '#/components/messages/userSignedUp' + bindings: + kafka: + topic: 'UserSignedUp' + partitions: 10 + replicas: 2 + topicConfiguration: + cleanup.policy: ["delete", "compact"] + retention.ms: 604800000 + retention.bytes: 1000000000 + delete.retention.ms: 86400000 + max.message.bytes: 1048588 +components: + messages: + userSignedUp: + bindings: + kafka: + key: + type: string + enum: ['myKey'] + schemaIdLocation: 'payload' + schemaIdPayloadEncoding: 'apicurio-new' + schemaLookupStrategy: 'TopicIdStrategy' + payload: + schemaFormat: 'application/vnd.apache.avro+json;version=1.9.0' + schema: + $ref: http://localhost:8080/apis/registry/v2/groups/my-group/artifacts/UserSignedUp +``` + ## Summary In this tutorial, you learned how to configure server and channel bindings. You also learned that bindings are essential when integrating Kafka with different systems, platforms, or protocols — especially in API specifications like AsyncAPI. From 4ef85429fe4bb7a59732e14bbb3f9b0283fcc5aa Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Wed, 13 Mar 2024 07:40:32 +0100 Subject: [PATCH 22/39] updated based on feedback from Dale. Used just channel.address --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 1 - 1 file changed, 1 deletion(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index ebfb59953ff1..91b3cd198dd4 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -148,7 +148,6 @@ channels: $ref: '#/components/messages/userSignedUp' bindings: kafka: - topic: 'UserSignedUp' partitions: 10 replicas: 2 topicConfiguration: From f50d8a83fc4129b546f3ada5f1ef773f5f512359 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Wed, 13 Mar 2024 18:06:11 +0100 Subject: [PATCH 23/39] update docs based on feedback --- .../tutorials/kafka/bindings-with-kafka.md | 82 ++++++++++++++++--- 1 file changed, 71 insertions(+), 11 deletions(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 91b3cd198dd4..133f0bd3be7e 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -10,17 +10,55 @@ In a previous tutorial, you learned how to manage schemas with a schema registry ## Background context -Bindings are essential for event-driven applications because they provide protocol-specific details, abstracting the complexities of message handling from your application's core logic. They enhance the API's clarity and usability by offering setup options and context for different protocols. Bindings include details like the topics your application reads from or writes to, message formatting, and rules for interacting with multiple data or messages. +Bindings are essential for event-driven applications because they provide protocol-specific details, abstracting the complexities of message handling from your application's core logic. They enhance the API's clarity and usability by offering setup options and context for different protocols. [Bindings](docs/concepts/asyncapi-document/adding-bindings) include details like the topics your application reads from or writes to, message formatting, and rules for interacting with multiple data or messages. In an AsyncAPI document, bindings can be added to various sections like servers, channels, or messages. They contain protocol-specific details unique to each protocol. Binding definitions let you specify functionalities specific to the protocol, which are not covered by AsyncAPI's core features. -You can configure several objects using Kafka bindings. However, for the scope of this tutorial, you will focus on four levels of bindings: [server bindings](https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object), [operations binding](https://github.com/asyncapi/bindings/tree/master/kafka#operation-binding-object), [channel bindings](https://github.com/asyncapi/bindings/tree/master/kafka#channel-binding-object) and [message bindings](https://github.com/asyncapi/bindings/tree/master/kafka#message-binding-object). +You can configure several objects using [Kafka bindings](https://github.com/asyncapi/bindings/tree/master/kafka#readme). However, for the scope of this tutorial, you will focus on four levels of bindings: server bindings, operations binding, channel bindings and message bindings. -Using the code snippets from the previous tutorial, where you learned [how to manage Avro schemas using a centralized schema registry that enables you to share schemas across multiple applications](pages/docs/tutorials/kafka/managing-schemas-using-schema-registry), you will add configurations for server, operations, channel, and message bindings. +Using the code snippets from the previous tutorial, where you learned [how to manage Avro schemas using a centralized schema registry that enables you to share schemas across multiple applications](/docs/tutorials/kafka/managing-schemas-using-schema-registry), you will add configurations for server, operations, channel, and message bindings. + +Below, you can find the updated Schema reference file that we'll be using for this tutorial. + +```yaml +asyncapi: 3.0.0 +info: + title: User Signup API + version: 1.0.0 + description: The API notifies you whenever a new user signs up in the application. +servers: + kafkaServer: + host: test.mykafkacluster.org:8092 + description: Kafka Server + protocol: kafka +operations: + onUserSignedUp: + action: receive + channel: + $ref: '#/channels/userSignedUp' +channels: + userSignedUp: + description: This channel contains a message per each user who signs up in our application. + address: user_signedup + messages: + userSignedUp: + $ref: '#/components/messages/userSignedUp' +components: + messages: + userSignedUp: + payload: + schemaFormat: 'application/vnd.apache.avro+json;version=1.9.0' + schema: + $ref: http://localhost:8080/apis/registry/v2/groups/my-group/artifacts/UserSignedUp +``` ## Add server bindings -Server bindings provide protocol-specific configuration details for connecting and interacting with a server. For server bindings, we will add three fields: +Server bindings provide protocol-specific configuration details for connecting and interacting with a server. + +Server bindings allows you to specify a `schemaRegistryUrl` which provides an API Url for a given server where a schema registry was used. A Schema registry is a repository for managing and validating messages' schemas. To learn more about schema registry read [this guide on message validation](https://www.asyncapi.com/docs/guides/message-validation#schema-registry-validation). + +`schemaRegistryVendor` is used optionally to refer to vendors or platforms that provide the schema registry service, in this case "Apicurio". ```yaml servers: @@ -28,21 +66,25 @@ servers: host: test.mykafkacluster.org:8092 description: Kafka Server protocol: kafka - production: bindings: kafka: schemaRegistryUrl: 'http://localhost:8080/apis/registry/' schemaRegistryVendor: 'apicurio' - bindingVersion: '0.5.0' + bindingVersion: '0.4.0' ``` -> Important: `Binding-version` is the field version of a binding. If omitted, the "latest" version MUST be assumed. The `bindingversion` field is an optional field that is available for all bindings. +[Learn more about server specific bindings.](https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object). +> Important: `BindingVersion` is the field version of a binding. If omitted, the "latest" version MUST be assumed. It specifies the version of the binding specification that is used to describe how an API interacts with Kafka. The `bindingVersion` field is an optional field that is available for all bindings and ensures that as the specifications for different messaging systems evolve, APIs based on these specifications can remain consistent, compatible, and maintainable over time. ## Add operation bindings Operation bindings object contains information about the operation representation in Kafka (eg. the way to consume messages). +The operation binding object provides a structured way to describe how a particular operation (publish, subscribe) should behave on a Kafka topic. The `groupid`, for example, is the Id of the consumer group, while the `cliendID` is the Id of the consumer within a consumer group. + +These configurations are vital for distributed message consumption and load balancing among consumers. Learn more about other fields you can configure under [operations binding](https://github.com/asyncapi/bindings/tree/master/kafka#operation-binding-object). + ```yaml operations: onUserSignedUp: @@ -51,6 +93,7 @@ operations: $ref: '#/channels/userSignedUp' bindings: kafka: + bindingVersion: '0.4.0' groupId: type: string enum: ['myGroupId'] @@ -61,7 +104,12 @@ operations: ## Add channel bindings -Channel bindings provide protocol-specific information for a particular channel. In Kafka, you can specify a given topic's number of partitions or replicas. +Channel bindings provide protocol-specific information for a particular channel. + +These configurations may include information about how to connect with the Kafka topic, plus any specific settings or behaviors to be used. The Channel Binding Object is part of AsyncAPI's wider bindings architecture, which specifies how the API interacts with the messaging system — in this case, Kafka. + +In Kafka, you can specify a given topic's number of partitions or replicas therefore, enabling parallel processing of data or consumers. Learn more about other fields that you can configure under [channel bindings](https://github.com/asyncapi/bindings/tree/master/kafka#channel-binding-object). + ```yaml channels: @@ -73,7 +121,7 @@ channels: $ref: '#/components/messages/userSignedUp' bindings: kafka: - topic: 'UserSignedUp' + bindingVersion: '0.4.0' partitions: 10 replicas: 2 topicConfiguration: @@ -84,10 +132,19 @@ channels: max.message.bytes: 1048588 ``` + +If you need to follow specific naming conventions for example, Kafka topic name is different from channel name. + + + ## Add message bindings Message bindings provide protocol-specific information for a specific message. Like the Kafka topic, it's associated with a message key (if any) and Kafka-specific properties. +For example, the `schemaIdLocation` field, if specified is used to indicate where the schema identifier (ID) for the message payload's schema is located. It is useful for message serialization and deserialization, enabling consumers to understand how to interpret the message payload. + +Learn more about other fields that you can configure under [message bindings](https://github.com/asyncapi/bindings/tree/master/kafka#message-binding-object) + ```yaml components: messages: @@ -100,7 +157,7 @@ components: schemaIdLocation: 'payload' schemaIdPayloadEncoding: 'apicurio-new' schemaLookupStrategy: 'TopicIdStrategy' - bindingVersion: '0.5.0' + bindingVersion: '0.4.0' payload: schemaFormat: 'application/vnd.apache.avro+json;version=1.9.0' schema: @@ -125,7 +182,7 @@ servers: kafka: schemaRegistryUrl: 'http://localhost:8080/apis/registry/' schemaRegistryVendor: 'apicurio' - bindingVersion: '0.5.0' + bindingVersion: '0.4.0' operations: onUserSignedUp: action: receive @@ -133,6 +190,7 @@ operations: $ref: '#/channels/userSignedUp' bindings: kafka: + bindingVersion: '0.4.0' groupId: type: string enum: ['myGroupId'] @@ -148,6 +206,7 @@ channels: $ref: '#/components/messages/userSignedUp' bindings: kafka: + bindingVersion: '0.4.0' partitions: 10 replicas: 2 topicConfiguration: @@ -161,6 +220,7 @@ components: userSignedUp: bindings: kafka: + bindingVersion: '0.4.0' key: type: string enum: ['myKey'] From b3f6d3d23c94e04c2078276888a01786fba5447d Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Wed, 13 Mar 2024 18:15:30 +0100 Subject: [PATCH 24/39] removed production --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 133f0bd3be7e..cf720fc3064e 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -6,7 +6,7 @@ weight: 300 ## Introduction -In a previous tutorial, you learned how to manage schemas with a schema registry. This tutorial teaches you how Kafka bindings function by defining Kafka messages and expanding your AsyncAPI document with protocol-specific details. +In a [previous tutorial](/docs/tutorials/kafka/managing-schemas-using-schema-registry.md), you learned how to manage schemas with a schema registry. This tutorial teaches you how Kafka bindings function by defining Kafka messages and expanding your AsyncAPI document with protocol-specific details. ## Background context @@ -177,7 +177,6 @@ servers: host: test.mykafkacluster.org:8092 description: Kafka Server protocol: kafka - production: bindings: kafka: schemaRegistryUrl: 'http://localhost:8080/apis/registry/' @@ -235,7 +234,7 @@ components: ## Summary -In this tutorial, you learned how to configure server and channel bindings. You also learned that bindings are essential when integrating Kafka with different systems, platforms, or protocols — especially in API specifications like AsyncAPI. +In this tutorial, you learned how to configure server, operation, message, and channel bindings. You also learned that bindings are essential when integrating Kafka with different systems, platforms, or protocols — especially in API specifications like AsyncAPI. ## Next steps From 822a08a23a1f8844f2059debf7ffa9937279d42d Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Thu, 14 Mar 2024 08:12:21 +0100 Subject: [PATCH 25/39] edited bindingVersion --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index cf720fc3064e..cbe125952187 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -75,7 +75,7 @@ servers: [Learn more about server specific bindings.](https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object). -> Important: `BindingVersion` is the field version of a binding. If omitted, the "latest" version MUST be assumed. It specifies the version of the binding specification that is used to describe how an API interacts with Kafka. The `bindingVersion` field is an optional field that is available for all bindings and ensures that as the specifications for different messaging systems evolve, APIs based on these specifications can remain consistent, compatible, and maintainable over time. +> Important: `BindingVersion` is the field version of a binding. It specifies the version of the binding specification that is used to describe how an API interacts with Kafka. The `bindingVersion` field is an optional field that is available for all bindings and ensures that as the specifications for different messaging systems evolve, APIs based on these specifications can remain consistent, compatible, and maintainable over time. ## Add operation bindings From 39f25e10f7aa37ae6fe4cafe58773472f8ed0c04 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Thu, 14 Mar 2024 11:31:55 +0100 Subject: [PATCH 26/39] Update pages/docs/tutorials/kafka/bindings-with-kafka.md Co-authored-by: Lukasz Gornicki --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index cbe125952187..9d235b3b2cab 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -58,7 +58,7 @@ Server bindings provide protocol-specific configuration details for connecting a Server bindings allows you to specify a `schemaRegistryUrl` which provides an API Url for a given server where a schema registry was used. A Schema registry is a repository for managing and validating messages' schemas. To learn more about schema registry read [this guide on message validation](https://www.asyncapi.com/docs/guides/message-validation#schema-registry-validation). -`schemaRegistryVendor` is used optionally to refer to vendors or platforms that provide the schema registry service, in this case "Apicurio". +`schemaRegistryVendor` is used optionally to refer to vendors or platforms that provide the schema registry service, in this case Apicurio Registry. ```yaml servers: From 37bba1de61daed6acbea2d24c6d778897671fffd Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Thu, 14 Mar 2024 11:34:22 +0100 Subject: [PATCH 27/39] Update pages/docs/tutorials/kafka/bindings-with-kafka.md Co-authored-by: Lukasz Gornicki --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 9d235b3b2cab..43d84d025044 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -75,7 +75,7 @@ servers: [Learn more about server specific bindings.](https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object). -> Important: `BindingVersion` is the field version of a binding. It specifies the version of the binding specification that is used to describe how an API interacts with Kafka. The `bindingVersion` field is an optional field that is available for all bindings and ensures that as the specifications for different messaging systems evolve, APIs based on these specifications can remain consistent, compatible, and maintainable over time. +> Important: `bindingVersion` is the field version of a binding. It specifies the version of the binding specification that is used to describe how an API interacts with Kafka. The `bindingVersion` field is an optional field that is available for all bindings and ensures that as the specifications for different messaging systems evolve, APIs based on these specifications can remain consistent, compatible, and maintainable over time. ## Add operation bindings From 3b2c3521df43e07310e1e36d18e84e2cd321cf60 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Thu, 14 Mar 2024 11:35:57 +0100 Subject: [PATCH 28/39] Update pages/docs/tutorials/kafka/bindings-with-kafka.md Co-authored-by: Dale Lane --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 43d84d025044..1bb9a1cc125e 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -106,7 +106,7 @@ operations: Channel bindings provide protocol-specific information for a particular channel. -These configurations may include information about how to connect with the Kafka topic, plus any specific settings or behaviors to be used. The Channel Binding Object is part of AsyncAPI's wider bindings architecture, which specifies how the API interacts with the messaging system — in this case, Kafka. +These configurations may include information how the Kafka topic has been configured. The Channel Binding Object is part of AsyncAPI's wider bindings architecture, which specifies how the API interacts with the messaging system — in this case, Kafka. In Kafka, you can specify a given topic's number of partitions or replicas therefore, enabling parallel processing of data or consumers. Learn more about other fields that you can configure under [channel bindings](https://github.com/asyncapi/bindings/tree/master/kafka#channel-binding-object). From f97c06c4adec752181f130d703dd5860beff224b Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Thu, 14 Mar 2024 11:36:11 +0100 Subject: [PATCH 29/39] Update pages/docs/tutorials/kafka/bindings-with-kafka.md Co-authored-by: Dale Lane --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 1bb9a1cc125e..8fbca189ae32 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -139,7 +139,7 @@ If you need to follow specific naming conventions for example, Kafka topic name ## Add message bindings -Message bindings provide protocol-specific information for a specific message. Like the Kafka topic, it's associated with a message key (if any) and Kafka-specific properties. +Message bindings provide protocol-specific information for a specific message. For Kafka topics, this can include how message keys are used, and details about how serialized message data has been encoded. For example, the `schemaIdLocation` field, if specified is used to indicate where the schema identifier (ID) for the message payload's schema is located. It is useful for message serialization and deserialization, enabling consumers to understand how to interpret the message payload. From bc47bf1d12ac33025e68caae171cdd5854495c17 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Thu, 14 Mar 2024 11:36:55 +0100 Subject: [PATCH 30/39] Update pages/docs/tutorials/kafka/bindings-with-kafka.md Valid document Co-authored-by: Lukasz Gornicki --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 8fbca189ae32..76e7d80b1000 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -220,12 +220,12 @@ components: bindings: kafka: bindingVersion: '0.4.0' - key: - type: string - enum: ['myKey'] - schemaIdLocation: 'payload' - schemaIdPayloadEncoding: 'apicurio-new' - schemaLookupStrategy: 'TopicIdStrategy' + key: + type: string + enum: ['myKey'] + schemaIdLocation: 'payload' + schemaIdPayloadEncoding: 'apicurio-new' + schemaLookupStrategy: 'TopicIdStrategy' payload: schemaFormat: 'application/vnd.apache.avro+json;version=1.9.0' schema: From d2b19a7066220365a9536f1da0bded280bd92dde Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Thu, 14 Mar 2024 11:41:41 +0100 Subject: [PATCH 31/39] update docs --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index cbe125952187..24e8334c747d 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -58,7 +58,7 @@ Server bindings provide protocol-specific configuration details for connecting a Server bindings allows you to specify a `schemaRegistryUrl` which provides an API Url for a given server where a schema registry was used. A Schema registry is a repository for managing and validating messages' schemas. To learn more about schema registry read [this guide on message validation](https://www.asyncapi.com/docs/guides/message-validation#schema-registry-validation). -`schemaRegistryVendor` is used optionally to refer to vendors or platforms that provide the schema registry service, in this case "Apicurio". +`schemaRegistryVendor` is used optionally to refer to vendors or platforms that provide the schema registry service, in this case "Apicurio". Learn more about [server bindings.](https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object). ```yaml servers: @@ -73,9 +73,8 @@ servers: bindingVersion: '0.4.0' ``` -[Learn more about server specific bindings.](https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object). -> Important: `BindingVersion` is the field version of a binding. It specifies the version of the binding specification that is used to describe how an API interacts with Kafka. The `bindingVersion` field is an optional field that is available for all bindings and ensures that as the specifications for different messaging systems evolve, APIs based on these specifications can remain consistent, compatible, and maintainable over time. +> Important: `BindingVersion` is the field version of a binding. It specifies the version of the binding specification that is used to describe how an API interacts with Kafka. The `bindingVersion` field is an optional field that is available for all bindings. ## Add operation bindings From fb2869a5caa2924ab8a5a5a37fc590e48a4af4a8 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Thu, 14 Mar 2024 11:46:11 +0100 Subject: [PATCH 32/39] Update pages/docs/tutorials/kafka/bindings-with-kafka.md Co-authored-by: Dale Lane --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index cb0184ca7437..13e3e0bcacce 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -91,7 +91,7 @@ operations: $ref: '#/channels/userSignedUp' bindings: kafka: - bindingVersion: '0.4.0' + bindingVersion: '0.5.0' groupId: type: string enum: ['myGroupId'] From ac7da566d6035a8d0ea8a8214a4438cb48a52ba6 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Thu, 14 Mar 2024 11:46:17 +0100 Subject: [PATCH 33/39] Update pages/docs/tutorials/kafka/bindings-with-kafka.md Co-authored-by: Dale Lane --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 13e3e0bcacce..038005813d6f 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -155,7 +155,7 @@ components: schemaIdLocation: 'payload' schemaIdPayloadEncoding: 'apicurio-new' schemaLookupStrategy: 'TopicIdStrategy' - bindingVersion: '0.4.0' + bindingVersion: '0.5.0' payload: schemaFormat: 'application/vnd.apache.avro+json;version=1.9.0' schema: From 449084922e63e9a898799c0c533364b4ba36fc04 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Thu, 14 Mar 2024 11:56:46 +0100 Subject: [PATCH 34/39] update docs --- .../tutorials/kafka/bindings-with-kafka.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index cb0184ca7437..3605e326f6ff 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -58,7 +58,7 @@ Server bindings provide protocol-specific configuration details for connecting a Server bindings allows you to specify a `schemaRegistryUrl` which provides an API Url for a given server where a schema registry was used. A Schema registry is a repository for managing and validating messages' schemas. To learn more about schema registry read [this guide on message validation](https://www.asyncapi.com/docs/guides/message-validation#schema-registry-validation). -`schemaRegistryVendor` is used optionally to refer to vendors or platforms that provide the schema registry service, in this case Apicurio Registry. +`schemaRegistryVendor` is used optionally to refer to vendors or platforms that provide the schema registry service, in this case Apicurio Registry. Learn more about other fields you can configure under [server bindings.](https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object). ```yaml servers: @@ -70,7 +70,7 @@ servers: kafka: schemaRegistryUrl: 'http://localhost:8080/apis/registry/' schemaRegistryVendor: 'apicurio' - bindingVersion: '0.4.0' + bindingVersion: '0.5.0' ``` > Important: `bindingVersion` is the field version of a binding. It specifies the version of the binding specification that is used to describe how an API interacts with Kafka. The `bindingVersion` field is an optional field that is available for all bindings. @@ -91,7 +91,7 @@ operations: $ref: '#/channels/userSignedUp' bindings: kafka: - bindingVersion: '0.4.0' + bindingVersion: '0.5.0' groupId: type: string enum: ['myGroupId'] @@ -119,7 +119,7 @@ channels: $ref: '#/components/messages/userSignedUp' bindings: kafka: - bindingVersion: '0.4.0' + bindingVersion: '0.5.0' partitions: 10 replicas: 2 topicConfiguration: @@ -155,7 +155,7 @@ components: schemaIdLocation: 'payload' schemaIdPayloadEncoding: 'apicurio-new' schemaLookupStrategy: 'TopicIdStrategy' - bindingVersion: '0.4.0' + bindingVersion: '0.5.0' payload: schemaFormat: 'application/vnd.apache.avro+json;version=1.9.0' schema: @@ -179,7 +179,7 @@ servers: kafka: schemaRegistryUrl: 'http://localhost:8080/apis/registry/' schemaRegistryVendor: 'apicurio' - bindingVersion: '0.4.0' + bindingVersion: '0.5.0' operations: onUserSignedUp: action: receive @@ -187,7 +187,7 @@ operations: $ref: '#/channels/userSignedUp' bindings: kafka: - bindingVersion: '0.4.0' + bindingVersion: '0.5.0' groupId: type: string enum: ['myGroupId'] @@ -203,7 +203,7 @@ channels: $ref: '#/components/messages/userSignedUp' bindings: kafka: - bindingVersion: '0.4.0' + bindingVersion: '0.5.0' partitions: 10 replicas: 2 topicConfiguration: @@ -217,7 +217,7 @@ components: userSignedUp: bindings: kafka: - bindingVersion: '0.4.0' + bindingVersion: '0.5.0' key: type: string enum: ['myKey'] From 9626df0238ac466e31f54185f1742ed203b639b4 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Thu, 14 Mar 2024 13:36:17 +0100 Subject: [PATCH 35/39] removed the note on kafka.topic --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 3605e326f6ff..0a6f0ae4c3c7 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -130,10 +130,6 @@ channels: max.message.bytes: 1048588 ``` - -If you need to follow specific naming conventions for example, Kafka topic name is different from channel name. - - ## Add message bindings From b3b1bb79d257128fb1620eb6b6ef4ca271cf97a8 Mon Sep 17 00:00:00 2001 From: Cynthia Peter Date: Thu, 14 Mar 2024 13:39:19 +0100 Subject: [PATCH 36/39] fixed link error --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 0a6f0ae4c3c7..2a28e0733c78 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -6,7 +6,7 @@ weight: 300 ## Introduction -In a [previous tutorial](/docs/tutorials/kafka/managing-schemas-using-schema-registry.md), you learned how to manage schemas with a schema registry. This tutorial teaches you how Kafka bindings function by defining Kafka messages and expanding your AsyncAPI document with protocol-specific details. +In a [previous tutorial](/docs/tutorials/kafka/managing-schemas-using-schema-registry), you learned how to manage schemas with a schema registry. This tutorial teaches you how Kafka bindings function by defining Kafka messages and expanding your AsyncAPI document with protocol-specific details. ## Background context From 3af3bab6d58627aa4d9a026050d4e610f0f99f88 Mon Sep 17 00:00:00 2001 From: Quetzalli Date: Fri, 15 Mar 2024 16:22:14 -0700 Subject: [PATCH 37/39] grammar fixes --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 2a28e0733c78..612cc3d42ec9 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -14,7 +14,7 @@ Bindings are essential for event-driven applications because they provide protoc In an AsyncAPI document, bindings can be added to various sections like servers, channels, or messages. They contain protocol-specific details unique to each protocol. Binding definitions let you specify functionalities specific to the protocol, which are not covered by AsyncAPI's core features. -You can configure several objects using [Kafka bindings](https://github.com/asyncapi/bindings/tree/master/kafka#readme). However, for the scope of this tutorial, you will focus on four levels of bindings: server bindings, operations binding, channel bindings and message bindings. +You can configure several objects using [Kafka bindings](https://github.com/asyncapi/bindings/tree/master/kafka#readme). However, for the scope of this tutorial, you will focus on four levels of bindings: server bindings, operations binding, channel bindings, and message bindings. Using the code snippets from the previous tutorial, where you learned [how to manage Avro schemas using a centralized schema registry that enables you to share schemas across multiple applications](/docs/tutorials/kafka/managing-schemas-using-schema-registry), you will add configurations for server, operations, channel, and message bindings. @@ -56,9 +56,9 @@ components: Server bindings provide protocol-specific configuration details for connecting and interacting with a server. -Server bindings allows you to specify a `schemaRegistryUrl` which provides an API Url for a given server where a schema registry was used. A Schema registry is a repository for managing and validating messages' schemas. To learn more about schema registry read [this guide on message validation](https://www.asyncapi.com/docs/guides/message-validation#schema-registry-validation). +Server bindings allow you to specify a `schemaRegistryUrl`, which provides an API URL for a given server where a schema registry was used. A Schema registry is a repository for managing and validating messages' schemas. To learn more about schema registry, read the [message validation guide for schema registry](https://www.asyncapi.com/docs/guides/message-validation#schema-registry-validation). -`schemaRegistryVendor` is used optionally to refer to vendors or platforms that provide the schema registry service, in this case Apicurio Registry. Learn more about other fields you can configure under [server bindings.](https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object). +`schemaRegistryVendor` is used optionally to refer to vendors or platforms that provide the schema registry service, in this case, Apicurio Registry. Learn about other fields you can configure under [server bindings.](https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object). ```yaml servers: From 56610de3339f90510cc3ace3aee80eb1eefb8877 Mon Sep 17 00:00:00 2001 From: Quetzalli Date: Fri, 15 Mar 2024 16:57:57 -0700 Subject: [PATCH 38/39] grammar fixes --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 612cc3d42ec9..437e3caf2374 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -18,7 +18,7 @@ You can configure several objects using [Kafka bindings](https://github.com/asyn Using the code snippets from the previous tutorial, where you learned [how to manage Avro schemas using a centralized schema registry that enables you to share schemas across multiple applications](/docs/tutorials/kafka/managing-schemas-using-schema-registry), you will add configurations for server, operations, channel, and message bindings. -Below, you can find the updated Schema reference file that we'll be using for this tutorial. +Below, you can find the updated schema reference file you'll use for this tutorial. ```yaml asyncapi: 3.0.0 @@ -56,7 +56,7 @@ components: Server bindings provide protocol-specific configuration details for connecting and interacting with a server. -Server bindings allow you to specify a `schemaRegistryUrl`, which provides an API URL for a given server where a schema registry was used. A Schema registry is a repository for managing and validating messages' schemas. To learn more about schema registry, read the [message validation guide for schema registry](https://www.asyncapi.com/docs/guides/message-validation#schema-registry-validation). +Server bindings allow you to specify a `schemaRegistryUrl`, which provides an API URL for a given server where a schema registry was used. A schema registry is a repository for managing and validating messages' schemas. To learn more about schema registry, read the [message validation guide for schema registry](https://www.asyncapi.com/docs/guides/message-validation#schema-registry-validation). `schemaRegistryVendor` is used optionally to refer to vendors or platforms that provide the schema registry service, in this case, Apicurio Registry. Learn about other fields you can configure under [server bindings.](https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object). From 87d457c12c86212e9fffa54f8551ccf56219315d Mon Sep 17 00:00:00 2001 From: Quetzalli Date: Fri, 15 Mar 2024 17:05:12 -0700 Subject: [PATCH 39/39] fix broken links --- pages/docs/tutorials/kafka/bindings-with-kafka.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pages/docs/tutorials/kafka/bindings-with-kafka.md b/pages/docs/tutorials/kafka/bindings-with-kafka.md index 437e3caf2374..bace0ce13a7f 100644 --- a/pages/docs/tutorials/kafka/bindings-with-kafka.md +++ b/pages/docs/tutorials/kafka/bindings-with-kafka.md @@ -6,11 +6,11 @@ weight: 300 ## Introduction -In a [previous tutorial](/docs/tutorials/kafka/managing-schemas-using-schema-registry), you learned how to manage schemas with a schema registry. This tutorial teaches you how Kafka bindings function by defining Kafka messages and expanding your AsyncAPI document with protocol-specific details. +[You learned how to manage schemas with a schema registry in the previous tutorial](/docs/tutorials/kafka/managing-schemas-using-schema-registry). This tutorial teaches you how Kafka bindings function by defining Kafka messages and expanding your AsyncAPI document with protocol-specific details. ## Background context -Bindings are essential for event-driven applications because they provide protocol-specific details, abstracting the complexities of message handling from your application's core logic. They enhance the API's clarity and usability by offering setup options and context for different protocols. [Bindings](docs/concepts/asyncapi-document/adding-bindings) include details like the topics your application reads from or writes to, message formatting, and rules for interacting with multiple data or messages. +Bindings are essential for event-driven applications because they provide protocol-specific details, abstracting the complexities of message handling from your application's core logic. They enhance the API's clarity and usability by offering setup options and context for different protocols. Bindings include the topics your application reads from or writes to, message formatting, and rules for interacting with multiple data or messages. In an AsyncAPI document, bindings can be added to various sections like servers, channels, or messages. They contain protocol-specific details unique to each protocol. Binding definitions let you specify functionalities specific to the protocol, which are not covered by AsyncAPI's core features. @@ -58,7 +58,7 @@ Server bindings provide protocol-specific configuration details for connecting a Server bindings allow you to specify a `schemaRegistryUrl`, which provides an API URL for a given server where a schema registry was used. A schema registry is a repository for managing and validating messages' schemas. To learn more about schema registry, read the [message validation guide for schema registry](https://www.asyncapi.com/docs/guides/message-validation#schema-registry-validation). -`schemaRegistryVendor` is used optionally to refer to vendors or platforms that provide the schema registry service, in this case, Apicurio Registry. Learn about other fields you can configure under [server bindings.](https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object). +`schemaRegistryVendor` is used optionally to refer to vendors or platforms that provide the schema registry service, in this case, Apicurio Registry. Learn about other fields you can configure under [server bindings](https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object). ```yaml servers: