Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Spécifier ses API asynchrones avec AsyncAPI - Devoxx France 2022 - Tools-in-Action

Spécifier ses API asynchrones avec AsyncAPI - Devoxx France 2022 - Tools-in-Action

AsyncAPI est le langage de description des API asynchrones très fortement inspiré de la spécification OpenAPI (aka Swagger). Avec l’émergence des architectures orientées événements, AsyncAPI est alors le bienvenu.

Nous verrons donc comment décrire très simplement et rapidement une API asynchrone, factoriser la description et générer une description moderne à publier en ligne !

Sébastien LECACHEUR

April 21, 2022
Tweet

More Decks by Sébastien LECACHEUR

Other Decks in Programming

Transcript

  1. Spécifier ses API asynchrones avec
    AsyncAPI
    {

    "fn": "Sébastien Lecacheur",

    "twitter": "@slecache",

    "org": "Odigo",

    "event": {

    "name": "Devoxx France",

    "type": "Tools in Action",

    "dt": {

    "start": "2022-04-21T18:30:00.000Z",

    "end": "2022-04-21T19:00:00.000Z"

    },

    "location": "Paris 242 AB"

    }

    }

    View full-size slide

  2. Agenda 📅
    📕 Définitions

    View full-size slide

  3. Agenda 📅
    📕 Définitions
    🏞️ Contexte

    View full-size slide

  4. Agenda 📅
    📕 Définitions
    🏞️ Contexte
    ⌨️ Demo AsyncAPI

    View full-size slide

  5. Agenda 📅
    📕 Définitions
    🏞️ Contexte
    ⌨️ Demo AsyncAPI
    🛫 Aller plus loin

    View full-size slide

  6. Définitions 📕

    View full-size slide

  7. Définitions 📕
    Qu’est-ce qu’une API asynchrone ?

    View full-size slide

  8. API 🧩
    faire dialoguer des applications

    View full-size slide

  9. API 🧩
    faire dialoguer des applications
    Consommateur d’un service

    View full-size slide

  10. API 🧩
    faire dialoguer des applications
    Consommateur d’un service
    Producteur du service

    View full-size slide

  11. Asynchrone 📣

    View full-size slide

  12. Asynchrone 📣
    qui n’attend pas une réponse dans l’immédiat

    View full-size slide

  13. Asynchrone 📣
    qui n’attend pas une réponse dans l’immédiat
    one-to-one : commande / résultat de traitement

    View full-size slide

  14. Asynchrone 📣
    qui n’attend pas une réponse dans l’immédiat
    one-to-one : commande / résultat de traitement
    one-to-many : notification / événement

    View full-size slide

  15. Contexte 🏞️
    Pour nos APIs asynchrones, nous cherchions…

    View full-size slide

  16. Contexte 🏞️
    Pour nos APIs asynchrones, nous cherchions…

    Une documentation pour les utilisateurs internes et
    externes,

    View full-size slide

  17. Contexte 🏞️
    Pour nos APIs asynchrones, nous cherchions…

    Une documentation pour les utilisateurs internes et
    externes,
    rédigée avant l’implémentation pour une approche
    contract first,

    View full-size slide

  18. Contexte 🏞️
    Pour nos APIs asynchrones, nous cherchions…

    Une documentation pour les utilisateurs internes et
    externes,
    rédigée avant l’implémentation pour une approche
    contract first,
    gérée comme du code source,

    View full-size slide

  19. Contexte 🏞️
    Pour nos APIs asynchrones, nous cherchions…

    Une documentation pour les utilisateurs internes et
    externes,
    rédigée avant l’implémentation pour une approche
    contract first,
    gérée comme du code source,
    et lisible par des humains.

    View full-size slide

  20. Qui a dit
    MS Word ?

    View full-size slide

  21. Documentation d’API 📖

    View full-size slide

  22. Documentation d’API 📖
    SDK, lib → JavaDoc, PHPDoc, JSDoc…

    View full-size slide

  23. Documentation d’API 📖
    SDK, lib → JavaDoc, PHPDoc, JSDoc…
    Web Services, REST → OpenAPI

    View full-size slide

  24. Documentation d’API 📖
    SDK, lib → JavaDoc, PHPDoc, JSDoc…
    Web Services, REST → OpenAPI
    Événements, messages

    View full-size slide

  25. Documentation d’API 📖
    SDK, lib → JavaDoc, PHPDoc, JSDoc…
    Web Services, REST → OpenAPI
    Événements, messages → AsyncAPI

    View full-size slide

  26. AsyncAPI 📋
    2016
    JSON/YAML
    version 2.3.0
    https://www.asyncapi.com
    https://github.com/asyncapi
    Linux Foundation

    View full-size slide

  27. De l’OpenAPI à AsyncAPI ⏩

    View full-size slide

  28. De l’OpenAPI à AsyncAPI ⏩

    View full-size slide

  29. Les protocoles ⚙️
    middlewares orientés messages : JMS, Kafka, RabbitMQ…
    streaming : WebSocket, Server-sent events…

    View full-size slide

  30. Format des messages ✉️

    View full-size slide

  31. Format des messages ✉️
    La définition du payload est libre.

    View full-size slide

  32. Format des messages ✉️
    La définition du payload est libre.
    JSON schema

    View full-size slide

  33. Format des messages ✉️
    La définition du payload est libre.
    JSON schema
    Apache Avro

    View full-size slide

  34. Format des messages ✉️
    La définition du payload est libre.
    JSON schema
    Apache Avro
    CloudEvents

    View full-size slide

  35. Format des messages ✉️
    La définition du payload est libre.
    JSON schema
    Apache Avro
    CloudEvents
    personnalisé

    View full-size slide

  36. Une API asynchrone ? 🖊️

    View full-size slide

  37. Une API asynchrone ? 🖊️
    un canal agent/presence:

    View full-size slide

  38. Une API asynchrone ? 🖊️
    un canal agent/presence:
    des opérations publish:

    subscribe:

    View full-size slide

  39. Une API asynchrone ? 🖊️
    un canal agent/presence:
    des opérations publish:

    subscribe:
    un format de représentation message:

    contentType: application/json

    examples:

    - name: login

    payload: {"type":"login",
    "agent":"xyzg0ht9"}

    View full-size slide

  40. Une API asynchrone ? 🖊️
    un canal agent/presence:
    des opérations publish:

    subscribe:
    un format de représentation message:

    contentType: application/json

    examples:

    - name: login

    payload: {"type":"login",
    "agent":"xyzg0ht9"}
    Votre premier AsyncAPI !

    View full-size slide

  41. {

    "event": {

    "name": "demo",

    "type": "start"

    }

    }

    View full-size slide

  42. Démo ⌨️
    édition - Studio (online/CLI)
    documentation - ag html/markdown
    top-down - ag java/spring
    bottom-up - springwolf @Annotation
    mocks - Microcks

    View full-size slide

  43. Aller plus loin 🛫
    Outils
    Parseurs
    (RabbitMQ)
    linters :
    bundlers : @asyncapi/bundler, json-merger
    optimizer : @asyncapi/optimizer
    Exemples
    Protocol bindings
    Scribano
    Spectral
    AsyncAPI Spec examples
    APIs.guru - asyncapi-directory
    API Tracker - AsyncAPI specs

    View full-size slide

  44. Aller plus encore plus loin 🚀
    Alternatives :
    Async(hronous )API Patterns
    EventCatalog.dev
    Event-based API Patterns and Practices
    AsyncAPI Online 2021 - From specification to production

    View full-size slide

  45. Ce qu’il faut retenir 💡

    View full-size slide

  46. Ce qu’il faut retenir 💡
    Agnostique (langage & middleware) 🌌

    View full-size slide

  47. Ce qu’il faut retenir 💡
    Agnostique (langage & middleware) 🌌
    Syntaxe proche d’OpenAPI ✌️

    View full-size slide

  48. Ce qu’il faut retenir 💡
    Agnostique (langage & middleware) 🌌
    Syntaxe proche d’OpenAPI ✌️
    Pas seulement de la documentation 🧰

    View full-size slide

  49. Ce qu’il faut retenir 💡
    Agnostique (langage & middleware) 🌌
    Syntaxe proche d’OpenAPI ✌️
    Pas seulement de la documentation 🧰
    Communauté ouverte 🤝

    View full-size slide

  50. Ce qu’il faut retenir 💡
    Agnostique (langage & middleware) 🌌
    Syntaxe proche d’OpenAPI ✌️
    Pas seulement de la documentation 🧰
    Communauté ouverte 🤝
    Ecosystème très jeune 👶

    View full-size slide

  51. Ce qu’il faut retenir 💡
    Agnostique (langage & middleware) 🌌
    Syntaxe proche d’OpenAPI ✌️
    Pas seulement de la documentation 🧰
    Communauté ouverte 🤝
    Ecosystème très jeune 👶
    Trop d’implémentations possibles 👾

    View full-size slide











  52. {

    "from": "@slecache",

    "to": "all",

    "event" : {

    "name": "Devoxx France",

    "type": "thanks"

    }

    }

    View full-size slide

  53. [

    {

    "from": "you",

    "to": "@slecache",

    "event" : {

    "type": "question",

    }

    },

    {

    "from": "@slecache",

    "to": "all",

    "event" : {

    "type": "response",

    }

    }

    ]

    View full-size slide