API Guidelines
  • adidas API Guidelines
  • General Guidelines
    • Introduction
    • API First
    • Contract
    • Immutability
    • Robustness
    • Common Data Types
    • Version Control System
    • Minimal API Surface
    • Rules for Extending
    • JSON
    • Security
    • Tooling
  • REST API Guidelines
    • Introduction
    • Core REST Principles
      • OpenAPI Specification
      • API Design Platform
      • Design Maturity
      • Testing
    • Protocol
      • HTTP
      • TLS
      • Separate Concerns
      • Request Methods
      • Status Codes
    • Message
      • Message Formats
      • Content Negotiation
      • HAL
      • Problem Detail
      • Foreign Key Relations
    • Application
      • Corporate Data Model
      • Common Data Types
    • Execution
      • Pagination
      • Long Running Tasks
        • Polling
        • Callback
        • Files Upload
      • Batch Operations
      • Search Requests
      • Query Requests with Large Inputs
      • Choosing Fields and Embedded Resources
      • Localization
      • Rate Limiting
      • Caching
      • Testing Enviroments
    • Evolution
      • Naming Conventions
      • Reserved Identifiers
      • URI Structure
      • Changes and Versioning
      • Phasing out Old Versions
    • Guides
      • API Testing CI Environment
      • Complete API Development
    • API Clients
      • Loose Coupling
    • Further References
  • Asynchronous API Guidelines
    • Introduction
    • Core Asynchronous Principles
      • Event Driven Architectures
      • Messages
        • Commands
        • Queries
        • Events
          • Events as Notifications
          • Events to Replicate Data
      • Protocols
      • Coupling
      • Bounded Context
      • Stream Processing
      • Naming Conventions
      • Tooling
        • Editors
        • Command Line Interface (CLI)
        • Generators
    • Kafka Asynchronous Guidelines
      • Introduction
        • Why AsyncAPI?
      • AsyncAPI Version
      • Internal vs Public Specifications
      • Key/Value Format
      • Message Headers
      • Specification Granularity
      • Self-Contained Specifications
        • Meaningful Descriptions
      • Schema Data Evolution
        • Backward Compatibility
        • Forward Compatibility
        • Full Compatibility
      • Automatic Schema Registration
      • Contact Information
      • AsyncAPI ID
      • Servers
      • Channels
      • Schemas
      • Security Schemes
      • External Docs
Powered by GitBook
On this page
  1. Asynchronous API Guidelines
  2. Kafka Asynchronous Guidelines
  3. Introduction

Why AsyncAPI?

Event-driven architectures are becoming increasingly popular for building scalable, responsive, and efficient applications. AsyncAPI plays a crucial role in this landscape by offering a standardized way to describe asynchronous APIs, similar to how OpenAPI does for REST APIs. AsyncAPI seeks to make the development, maintenance, and testing of asynchronous APIs easier by providing a machine-readable specification.

It supports various messaging protocols, including MQTT, Web Socket, Kafka, AMQP, and more, making it versatile for different use cases. In adidas, AsyncAPI is used mainly to document Kafka resources created across the company in the scope of the Streaming Platform, but nothing prevents you from using it for a different purpose.

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.

  • 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.

  • 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.

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

Will be easy to answer once this catalogue is in place. Also, it is important to have a good discoverability and search & filtering capabilities.

PreviousIntroductionNextAsyncAPI Version

Last updated 1 year ago