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 !

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 Slide

2. Agenda 📅
   

   View Slide

3. Agenda 📅
   📕 Définitions
   

   View Slide

4. Agenda 📅
   📕 Définitions
   🏞️ Contexte
   

   View Slide

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

   View Slide

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

   View Slide

7. Définitions 📕
   

   View Slide

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

   View Slide

9. API 🧩
   

   View Slide

10. API 🧩
    faire dialoguer des applications
    

    View Slide

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

    View Slide

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

    View Slide

13. Asynchrone 📣
    

    View Slide

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

    View Slide

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

    View Slide

16. 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 Slide

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

    View Slide

18. Contexte 🏞️
    Pour nos APIs asynchrones, nous cherchions…
    
    Une documentation pour les utilisateurs internes et
    externes,
    

    View 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,
    

    View Slide

20. 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 Slide

21. 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 Slide

22. Qui a dit
    MS Word ?
    

    View Slide

23. Documentation d’API 📖
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

29. De l’OpenAPI à AsyncAPI ⏩
    

    View Slide

30. De l’OpenAPI à AsyncAPI ⏩
    

    View Slide

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

    View Slide

32. Format des messages ✉️
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

38. Une API asynchrone ? 🖊️
    

    View Slide

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

    View Slide

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

    View Slide

41. 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 Slide

42. 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 Slide

43. {
    
    "event": {
    
    "name": "demo",
    
    "type": "start"
    
    }
    
    }
    
    

    View Slide

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

    View Slide

45. 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 Slide

46. 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 Slide

47. Ce qu’il faut retenir 💡
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

52. 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 Slide

53. 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 Slide

54. 
    
    
    
    
    
    
    
    
    
    {
    
    "from": "@slecache",
    
    "to": "all",
    
    "event" : {
    
    "name": "Devoxx France",
    
    "type": "thanks"
    
    }
    
    }
    
    

    View Slide

55. [
    
    {
    
    "from": "you",
    
    "to": "@slecache",
    
    "event" : {
    
    "type": "question",
    
    }
    
    },
    
    {
    
    "from": "@slecache",
    
    "to": "all",
    
    "event" : {
    
    "type": "response",
    
    }
    
    }
    
    ]
    
    

    View Slide