Mirrors/api-guidelines
1
0
Fork 0
mirror of https://github.com/adidas/api-guidelines.git synced 2025-10-25 15:19:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

FDP-5206 - Update guidelines and format

Browse Source
This commit is contained in:
Guillermo Lagunas
2025-06-10 16:01:34 +02:00
parent f4486b00b5
commit c587e3e014
15 changed files with 72 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
asynchronous-api-guidelines/kafka-asynchronous-guidelines/a_introduction/README.md
View File

@@ -2,7 +2,7 @@
This section is specific to the definition of API specs with [AsyncAPI](https://www.asyncapi.com/) for Kafka protocol.
Also, take into account that across the section there will be multiple references to this [AsyncAPI reference specification](https://design.api.3stripes.io/apis/adidas/asyncapi-adoption-initiative/1.0.0) which is publicly available for reference. 
Also, take into account that across the section there will be multiple references to this [AsyncAPI reference specification](https://design.api.3stripes.io/apis/adidas/asyncapi-adoption-initiative/1.0.0) which is publicly available for reference.
#### Kafka to AsyncAPI concept mapping

24
asynchronous-api-guidelines/kafka-asynchronous-guidelines/a_introduction/why-asyncapi.md
View File

@@ -7,24 +7,24 @@ It supports various messaging protocols, including MQTT, Web Socket, Kafka, AMQP
The benefits of using AsyncAPI are, amongst others:
* Standardization
* AsyncAPI defines a STANDARD format (YAML or JSON) for describing asynchronous APIs.
* By defining the structure of messages, channels, and events, you can ensure that all components adhere to the same conventions.
* Using a single standard ensures consistency in the design and documentation of all your asynchronous APIs.
* This simplifies integration, maintenance, and troubleshooting across different parts of your system.
* AsyncAPI defines a STANDARD format (YAML or JSON) for describing asynchronous APIs
* By defining the structure of messages, channels, and events, you can ensure that all components adhere to the same conventions
* Using a single standard ensures consistency in the design and documentation of all your asynchronous APIs
* This simplifies integration, maintenance, and troubleshooting across different parts of your system
* Improved Developer Experience
* AsyncAPI documents the messages being exchanged, their structure, and the events triggered by them.
* It provides developers with a clear picture of how to interact with the API, what data to expect, and how to interpret responses without digging into the implementation details. 
* AsyncAPI documents the messages being exchanged, their structure, and the events triggered by them
* It provides developers with a clear picture of how to interact with the API, what data to expect, and how to interpret responses without digging into the implementation details
* Code scaffolding
* Using tools like asyncapi-generator allow to easily generate the skeleton of applications that can work with the resources described in the spec.
* This can be done in different programming languages (Python, Java, Node.js. ...), reducing significantly the development time and the coding errors.
* Design-first approach: It encourages designing the API first before writing code, leading to better planned and more reliable APIs.
* Using tools like asyncapi-generator allow to easily generate the skeleton of applications that can work with the resources described in the spec
* This can be done in different programming languages (Python, Java, Node.js. ...), reducing significantly the development time and the coding errors
* Design-first approach: It encourages designing the API first before writing code, leading to better planned and more reliable APIs
In addition to those benefits, Platform & Engineering is working hard to create a data catalogue built upon AsyncAPI that allows to have a good level of discoverability, allowing teams to be able to find exactly the data they need with regards to any data object in the company.
Questions like:
* Who is responsible for a specific data object
* Where is that data hosted
* Which kind of information is available
* Who is responsible for a specific data object?
* Where is that data hosted?
* Which kind of information is available?
Will be easy to answer once this catalogue is in place. Also, it is important to have a good discoverability and search & filtering capabilities.