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" } }
2. Agenda 📅
3. Agenda 📅 📕 Définitions
4. Agenda 📅 📕 Définitions 🏞️ Contexte
5. Agenda 📅 📕 Définitions 🏞️ Contexte ⌨️ Demo AsyncAPI
6. Agenda 📅 📕 Définitions 🏞️ Contexte ⌨️ Demo AsyncAPI 🛫 Aller plus loin
7. Définitions 📕
8. Définitions 📕 Qu’est-ce qu’une API asynchrone ?
9. API 🧩
10. API 🧩 faire dialoguer des applications
11. API 🧩 faire dialoguer des applications Consommateur d’un service
12. API 🧩 faire dialoguer des applications Consommateur d’un service Producteur du service
13. Asynchrone 📣
14. Asynchrone 📣 qui n’attend pas une réponse dans l’immédiat
15. Asynchrone 📣 qui n’attend pas une réponse dans l’immédiat one-to-one : commande / résultat de traitement
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
17. Contexte 🏞️ Pour nos APIs asynchrones, nous cherchions…
18. Contexte 🏞️ Pour nos APIs asynchrones, nous cherchions… Une documentation pour les utilisateurs internes et externes,
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,
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,
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.
22. Qui a dit MS Word ?
23. Documentation d’API 📖
24. Documentation d’API 📖 SDK, lib → JavaDoc, PHPDoc, JSDoc…
25. Documentation d’API 📖 SDK, lib → JavaDoc, PHPDoc, JSDoc… Web Services, REST → OpenAPI
26. Documentation d’API 📖 SDK, lib → JavaDoc, PHPDoc, JSDoc… Web Services, REST → OpenAPI Événements, messages
27. Documentation d’API 📖 SDK, lib → JavaDoc, PHPDoc, JSDoc… Web Services, REST → OpenAPI Événements, messages → AsyncAPI
28. AsyncAPI 📋 2016 JSON/YAML version 2.3.0 https://www.asyncapi.com https://github.com/asyncapi Linux Foundation
29. De l’OpenAPI à AsyncAPI ⏩
30. De l’OpenAPI à AsyncAPI ⏩
31. Les protocoles ⚙️ middlewares orientés messages : JMS, Kafka, RabbitMQ… streaming : WebSocket, Server-sent events…
32. Format des messages ✉️
33. Format des messages ✉️ La définition du payload est libre.
34. Format des messages ✉️ La définition du payload est libre. JSON schema
35. Format des messages ✉️ La définition du payload est libre. JSON schema Apache Avro
36. Format des messages ✉️ La définition du payload est libre. JSON schema Apache Avro CloudEvents
37. Format des messages ✉️ La définition du payload est libre. JSON schema Apache Avro CloudEvents personnalisé
38. Une API asynchrone ? 🖊️
39. Une API asynchrone ? 🖊️ un canal agent/presence:
40. Une API asynchrone ? 🖊️ un canal agent/presence: des opérations publish: subscribe:
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"}
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 !
43. { "event": { "name": "demo", "type": "start" } }
44. Démo ⌨️ édition - Studio (online/CLI) documentation - ag html/markdown top-down - ag java/spring bottom-up - springwolf @Annotation mocks - Microcks
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
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
47. Ce qu’il faut retenir 💡
48. Ce qu’il faut retenir 💡 Agnostique (langage & middleware) 🌌
49. Ce qu’il faut retenir 💡 Agnostique (langage & middleware) 🌌 Syntaxe proche d’OpenAPI ✌️
50. Ce qu’il faut retenir 💡 Agnostique (langage & middleware) 🌌 Syntaxe proche d’OpenAPI ✌️ Pas seulement de la documentation 🧰
51. Ce qu’il faut retenir 💡 Agnostique (langage & middleware) 🌌 Syntaxe proche d’OpenAPI ✌️ Pas seulement de la documentation 🧰 Communauté ouverte 🤝
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 👶
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 👾
54. { "from": "@slecache", "to": "all", "event" : { "name": "Devoxx France", "type": "thanks" } }
55. [ { "from": "you", "to": "@slecache", "event" : { "type": "question", } }, { "from": "@slecache", "to": "all", "event" : { "type": "response", } } ]