From d496d3958495afd73f3d70a4bbc91762c3538fe5 Mon Sep 17 00:00:00 2001 From: "Perez, JuanManuel" Date: Fri, 10 May 2024 10:27:20 +0000 Subject: [PATCH] GITBOOK-3: Some structure fixes --- SUMMARY.md | 15 ++++++++------- .../core-asynchronous-principles/coupling.md | 2 +- .../core-asynchronous-principles/j_protocols.md | 4 +++- .../messages/README.md | 7 +++++++ .../{ => messages}/commands.md | 0 .../d_basic_concepts_events/README.md | 0 .../events-as-notifications.md | 0 .../events-to-replicate-data.md | 0 .../{ => messages}/query.md | 0 .../d_spec_granularity.md | 4 ++-- .../e_meaningful_descriptions.md | 3 --- .../backward-compatibility.md | 4 ++-- .../forward-compatibility.md | 2 +- .../f_schema_data_evolution/full-compatibility.md | 2 +- .../README.md} | 2 +- .../e_meaningful_descriptions.md | 3 +++ 16 files changed, 29 insertions(+), 19 deletions(-) create mode 100644 asynchronous-api-guidelines/core-asynchronous-principles/messages/README.md rename asynchronous-api-guidelines/core-asynchronous-principles/{ => messages}/commands.md (100%) rename asynchronous-api-guidelines/core-asynchronous-principles/{ => messages}/d_basic_concepts_events/README.md (100%) rename asynchronous-api-guidelines/core-asynchronous-principles/{ => messages}/d_basic_concepts_events/events-as-notifications.md (100%) rename asynchronous-api-guidelines/core-asynchronous-principles/{ => messages}/d_basic_concepts_events/events-to-replicate-data.md (100%) rename asynchronous-api-guidelines/core-asynchronous-principles/{ => messages}/query.md (100%) delete mode 100644 asynchronous-api-guidelines/kafka-asynchronous-guidelines/e_meaningful_descriptions.md rename asynchronous-api-guidelines/kafka-asynchronous-guidelines/{f_self_contained_specs.md => f_self_contained_specs/README.md} (92%) create mode 100644 asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_self_contained_specs/e_meaningful_descriptions.md diff --git a/SUMMARY.md b/SUMMARY.md index fc45e79..74aec4f 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -72,12 +72,13 @@ * [Introduction](asynchronous-api-guidelines/01\_introduction/a\_introduction.md) * [Core Asynchronous Principles](asynchronous-api-guidelines/core-asynchronous-principles/README.md) * [Event Driven Architectures](asynchronous-api-guidelines/core-asynchronous-principles/b\_basic\_concepts\_edas.md) - * [Events](asynchronous-api-guidelines/core-asynchronous-principles/d\_basic\_concepts\_events/README.md) - * [Events as Notifications](asynchronous-api-guidelines/core-asynchronous-principles/d\_basic\_concepts\_events/events-as-notifications.md) - * [Events to Replicate Data](asynchronous-api-guidelines/core-asynchronous-principles/d\_basic\_concepts\_events/events-to-replicate-data.md) + * [Messages](asynchronous-api-guidelines/core-asynchronous-principles/messages/README.md) + * [Commands](asynchronous-api-guidelines/core-asynchronous-principles/messages/commands.md) + * [Queries](asynchronous-api-guidelines/core-asynchronous-principles/messages/query.md) + * [Events](asynchronous-api-guidelines/core-asynchronous-principles/messages/d\_basic\_concepts\_events/README.md) + * [Events as Notifications](asynchronous-api-guidelines/core-asynchronous-principles/messages/d\_basic\_concepts\_events/events-as-notifications.md) + * [Events to Replicate Data](asynchronous-api-guidelines/core-asynchronous-principles/messages/d\_basic\_concepts\_events/events-to-replicate-data.md) * [Protocols](asynchronous-api-guidelines/core-asynchronous-principles/j\_protocols.md) - * [Commands](asynchronous-api-guidelines/core-asynchronous-principles/commands.md) - * [Query](asynchronous-api-guidelines/core-asynchronous-principles/query.md) * [Coupling](asynchronous-api-guidelines/core-asynchronous-principles/coupling.md) * [Bounded Context](asynchronous-api-guidelines/core-asynchronous-principles/bounded-context.md) * [Stream Processing](asynchronous-api-guidelines/core-asynchronous-principles/stream-processing.md) @@ -94,8 +95,8 @@ * [Key/Value Format](asynchronous-api-guidelines/kafka-asynchronous-guidelines/g\_key\_value\_format.md) * [Message Headers](asynchronous-api-guidelines/kafka-asynchronous-guidelines/h\_message\_headers.md) * [Specification Granularity](asynchronous-api-guidelines/kafka-asynchronous-guidelines/d\_spec\_granularity.md) - * [Meaningful Descriptions](asynchronous-api-guidelines/kafka-asynchronous-guidelines/e\_meaningful\_descriptions.md) - * [Self-Contained Specifications](asynchronous-api-guidelines/kafka-asynchronous-guidelines/f\_self\_contained\_specs.md) + * [Self-Contained Specifications](asynchronous-api-guidelines/kafka-asynchronous-guidelines/f\_self\_contained\_specs/README.md) + * [Meaningful Descriptions](asynchronous-api-guidelines/kafka-asynchronous-guidelines/f\_self\_contained\_specs/e\_meaningful\_descriptions.md) * [Schema Data Evolution](asynchronous-api-guidelines/kafka-asynchronous-guidelines/f\_schema\_data\_evolution/README.md) * [Backward Compatibility](asynchronous-api-guidelines/kafka-asynchronous-guidelines/f\_schema\_data\_evolution/backward-compatibility.md) * [Forward Compatibility](asynchronous-api-guidelines/kafka-asynchronous-guidelines/f\_schema\_data\_evolution/forward-compatibility.md) diff --git a/asynchronous-api-guidelines/core-asynchronous-principles/coupling.md b/asynchronous-api-guidelines/core-asynchronous-principles/coupling.md index 5881054..90e52cd 100644 --- a/asynchronous-api-guidelines/core-asynchronous-principles/coupling.md +++ b/asynchronous-api-guidelines/core-asynchronous-principles/coupling.md @@ -2,7 +2,7 @@ The term coupling can be understood as the impact that a change in one component will have on other components. In the end, it is related to the amount of things that a given component shares with others. The more is shared, the more tight is the coupling. -**Note:** A tighter coupling is not necessarily a bad thing, it depends on the situation. It will be necessary to assess the tradeoff between provide as much information as possible and to avoid having to change several components as a result of something changing in other component. +**Note:** A tighter coupling is not necessarily a bad thing, it depends on the situation. It will be necessary to assess the trade-off between providing as much information as possible and to avoid having to change several components as a result of something changing in other component. The coupling of a single component is actually a function of these factors: diff --git a/asynchronous-api-guidelines/core-asynchronous-principles/j_protocols.md b/asynchronous-api-guidelines/core-asynchronous-principles/j_protocols.md index 87bf9f4..0ad2825 100644 --- a/asynchronous-api-guidelines/core-asynchronous-principles/j_protocols.md +++ b/asynchronous-api-guidelines/core-asynchronous-principles/j_protocols.md @@ -5,7 +5,9 @@ Protocols define how clients and servers communicate in an asynchronous architec The accepted protocols for asynchronous APIs are: * **Kafka** - * [Kafka Asynchronous Guidelines ](../kafka-asynchronous-guidelines/) + * [Kafka Asynchronous Guidelines](../kafka-asynchronous-guidelines/) * **HTTPS** * **WebSockets** * **MQTT** + +**Note** Guidelines for non-kafka protocols are not available at this point, but they might be added in the future. diff --git a/asynchronous-api-guidelines/core-asynchronous-principles/messages/README.md b/asynchronous-api-guidelines/core-asynchronous-principles/messages/README.md new file mode 100644 index 0000000..3943c48 --- /dev/null +++ b/asynchronous-api-guidelines/core-asynchronous-principles/messages/README.md @@ -0,0 +1,7 @@ +# Messages + +A message in general is a piece of information that travels from an emitter to a receiver. There are different types of messages: + +* Commands +* Queries +* Events diff --git a/asynchronous-api-guidelines/core-asynchronous-principles/commands.md b/asynchronous-api-guidelines/core-asynchronous-principles/messages/commands.md similarity index 100% rename from asynchronous-api-guidelines/core-asynchronous-principles/commands.md rename to asynchronous-api-guidelines/core-asynchronous-principles/messages/commands.md diff --git a/asynchronous-api-guidelines/core-asynchronous-principles/d_basic_concepts_events/README.md b/asynchronous-api-guidelines/core-asynchronous-principles/messages/d_basic_concepts_events/README.md similarity index 100% rename from asynchronous-api-guidelines/core-asynchronous-principles/d_basic_concepts_events/README.md rename to asynchronous-api-guidelines/core-asynchronous-principles/messages/d_basic_concepts_events/README.md diff --git a/asynchronous-api-guidelines/core-asynchronous-principles/d_basic_concepts_events/events-as-notifications.md b/asynchronous-api-guidelines/core-asynchronous-principles/messages/d_basic_concepts_events/events-as-notifications.md similarity index 100% rename from asynchronous-api-guidelines/core-asynchronous-principles/d_basic_concepts_events/events-as-notifications.md rename to asynchronous-api-guidelines/core-asynchronous-principles/messages/d_basic_concepts_events/events-as-notifications.md diff --git a/asynchronous-api-guidelines/core-asynchronous-principles/d_basic_concepts_events/events-to-replicate-data.md b/asynchronous-api-guidelines/core-asynchronous-principles/messages/d_basic_concepts_events/events-to-replicate-data.md similarity index 100% rename from asynchronous-api-guidelines/core-asynchronous-principles/d_basic_concepts_events/events-to-replicate-data.md rename to asynchronous-api-guidelines/core-asynchronous-principles/messages/d_basic_concepts_events/events-to-replicate-data.md diff --git a/asynchronous-api-guidelines/core-asynchronous-principles/query.md b/asynchronous-api-guidelines/core-asynchronous-principles/messages/query.md similarity index 100% rename from asynchronous-api-guidelines/core-asynchronous-principles/query.md rename to asynchronous-api-guidelines/core-asynchronous-principles/messages/query.md diff --git a/asynchronous-api-guidelines/kafka-asynchronous-guidelines/d_spec_granularity.md b/asynchronous-api-guidelines/kafka-asynchronous-guidelines/d_spec_granularity.md index 614942e..a2745fd 100644 --- a/asynchronous-api-guidelines/kafka-asynchronous-guidelines/d_spec_granularity.md +++ b/asynchronous-api-guidelines/kafka-asynchronous-guidelines/d_spec_granularity.md @@ -1,7 +1,7 @@ # Specification Granularity -In adidas all resources are grouped by namespace. +In adidas streaming platform, all resources are grouped by namespaces. For that reason specs **SHOULD** be created with a relation 1:1 with namespaces. In other words, every namespace will have an AsyncAPI spec including all the assets belonging to that namespace. -Different granularities **MAY** be chosen depending on the needs. +Different granularities **MAY** be chosen depending on the needs. diff --git a/asynchronous-api-guidelines/kafka-asynchronous-guidelines/e_meaningful_descriptions.md b/asynchronous-api-guidelines/kafka-asynchronous-guidelines/e_meaningful_descriptions.md deleted file mode 100644 index 6731532..0000000 --- a/asynchronous-api-guidelines/kafka-asynchronous-guidelines/e_meaningful_descriptions.md +++ /dev/null @@ -1,3 +0,0 @@ -# Meaningful Descriptions - -All fields included in the specs **MUST** include a proper description. diff --git a/asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_schema_data_evolution/backward-compatibility.md b/asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_schema_data_evolution/backward-compatibility.md index 713214e..2a74c4b 100644 --- a/asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_schema_data_evolution/backward-compatibility.md +++ b/asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_schema_data_evolution/backward-compatibility.md @@ -7,9 +7,9 @@ There are two variants here: The operations that preserve backward compatibility are: -* Delete fields +* Deleting fields * Consumers with the newer version will just ignore the non-existing fields -* Add optional fields (with default values) +* Adding optional fields (with default values) * Consumers will set the default value for the missing fields in their schema version
diff --git a/asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_schema_data_evolution/forward-compatibility.md b/asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_schema_data_evolution/forward-compatibility.md index 618bb54..9b205ca 100644 --- a/asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_schema_data_evolution/forward-compatibility.md +++ b/asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_schema_data_evolution/forward-compatibility.md @@ -9,7 +9,7 @@ The operations that preserve forward compatibility are: * Adding a new field * Consumers will ignore the fields that are not defined in their schema version -* Delete optional fields (with default values) +* Deleting optional fields (with default values) * Consumers will use the default value for the missing fields defined in their schema version
diff --git a/asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_schema_data_evolution/full-compatibility.md b/asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_schema_data_evolution/full-compatibility.md index b5209e5..844c792 100644 --- a/asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_schema_data_evolution/full-compatibility.md +++ b/asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_schema_data_evolution/full-compatibility.md @@ -10,6 +10,6 @@ This is a combination of both compatibility types (backward and forward). It als This mode is preserved only if using the following operations * Adding optional fields (with default values) -* Delete optional fields (with default values) +* Deleting optional fields (with default values)
diff --git a/asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_self_contained_specs.md b/asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_self_contained_specs/README.md similarity index 92% rename from asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_self_contained_specs.md rename to asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_self_contained_specs/README.md index 318215b..6824b95 100644 --- a/asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_self_contained_specs.md +++ b/asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_self_contained_specs/README.md @@ -1,3 +1,3 @@ # Self-Contained Specifications -All AsyncAPI specification **SHOULD** include as much information as needed in order to make the spec self-contained and clearly documented +All AsyncAPI specification **SHOULD** include as much information as needed in order to make the spec self-contained and clearly documented. diff --git a/asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_self_contained_specs/e_meaningful_descriptions.md b/asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_self_contained_specs/e_meaningful_descriptions.md new file mode 100644 index 0000000..4ab2272 --- /dev/null +++ b/asynchronous-api-guidelines/kafka-asynchronous-guidelines/f_self_contained_specs/e_meaningful_descriptions.md @@ -0,0 +1,3 @@ +# Meaningful Descriptions + +AsyncAPI specs **MUST** make use of the _description_ fields, including there meaningful information to understand the purpose of the different elements.