[POITOUJUG24] Le versioning des APIs REST Dans la vraie vie, on fait comment?

Transcript

1. Le versioning des APIs REST Dans la vraie vie, on fait comment? Alexandre TOURET
3. L’ API
4. La vue haut niveau
5. Sous le capot
7. Let's version this API
8. Alexandre TOURET Architecte logiciel, Developer Advocate @touret_alex blog.touret.info alexandre-touret Qui suis-je?
9. We design payments technology that powers the growth of millions of businesses around the world. 7000+ engineers in over 40 countries Managing 43+ billion transactions per year €250M R D every year Handling 150+ payment methods #1 European payment processor
10. Delivery CI/CD Organisation du code Sécurité Compatibilité ascendante Impacts
11. Avant tout ça … V1
12. L’ API V1
13. • Est- q j’ ? • Comment gérer le versioning ? • Combien de versions puis-je gérer en même temps ? • Quelle est la compatibilité de la plateforme? • Quelle est votre gestion de configuration et quels sont les impacts? • Quid de la sécurité? Quelques questions à se poser
14. Une version dépréciée Une version courante Combien de versions concurrentes?
15. Q ’ - q ’ ? On versionne les changements bloquants sur le contrat de services (opérations ou données)
16. ✓ adding an operation ✓ adding an optional parameter ✓ adding an optional request header ✓ adding a response field ✓ adding a response header ✓ adding enum values ✓ removing an entire operation ✓ removing or renaming a parameter ✓ removing or renaming a response field ✓ adding a new required parameter ✓ making a previously optional parameter required ✓ changing the type of a parameter or response field ✓ removing enum values ✓ adding a new validation rule to an existing parameter ✓ changing authentication or authorization requirements Les changements selon GitHub https://docs.github.com/en/rest/overview/api-versions?apiVersion=2022-11-28 Bloquants Non-bloquants
17. Une modification bloquante dans le contrat de services Par exemple : dans notre objet Book un auteur devient une liste ’ C’ -à-dire ? Q ’ - q ’ q ?
18. Des changements non bloquants? Les changements non bloquants peuvent être ajoutés sans versioning
19. Ajout ’ é et données
20. Comment spécifier la version ? URL Exemple /v1/api/books Header HTTP Exemple X-API-VERSION : v1 Content-Type Exemple Accept: application/vnd.myn ame.v1+json RFC 9110
22. é ’URL Le changement de version représente des changements bloquants é ’URL j à V1… Spécification de la version dans le header "X-GitHub-Api-Version” Et les grands du web?
23. Positionner une version dans ’UR Si vous voulez repousser ’ du versioning /v1/api/books
25. Un nouveau client et de nouvelles fonctionnalités (V2)
27. La fonctionnalité majeure de la V2 Gestion ’ liste ’ V2 V1
28. Identifier les changements bloquants https://www.oasdiff.com
29. Contrat de services Bases de données Compatibilité avec la V1 Impacts
30. V2 V1 V2 V1
31. Quid de la base de données (relationnelle)? L V2 V1
32. Deux bases de données?
33. D ’ à la mise en production
35. Main Feature Hotfix Develop Release V1 V2 V2.1 Release avec la liste des auteurs Compatibilité ascendante V1.1
36. Gestion de la configuration
37. http :8888/rest-book/v1 { "label": null, "name": "rest-book", "profiles": [ "v1" ], "propertySources": [ { "name": "classpath:/config/rest-book-v1.yml", "source": { "booknumbers.api.timeout_sec": 2, "booknumbers.api.url": "http://127.0.0.1:8081/v1/isbns", "logging.level.org.hibernate.stat": "info", […] } Un exemple avec Spring Cloud Config
38. • JAR, ZIP, Charts Helm, Images Docker Un livrable par branche/tag • De manière dynamique (serveur de configuration) • Statique (Config Maps) Configuration • Bases de données • Divers Scripts Les livrables impactés par une version
39. • U ’ exécution par version • Centralisez la gestion des versions par une API Gateway L ’ é
40. q • L’ y versions (V1 et V2) • Elle transforme les requêtes et réponses de la V1 au format V2 Et si on ne gardait q ’un service?
41. ├── │ └── touret │ └── │ └── │ ├── │ │ ├── 1 │ │ ├── 2 │ │ ├── dto │ │ ├── y │ │ ├── │ │ ├── │ │ ├── y │ │ └── Gérer les versions dans la base de code: 1 version = 1 package Une autre manière de faire ├── │ └── touret │ └── 1 │ └── 2
42. • Identifiez qui utilise chaque version de votre API • Mettez en place des tableaux de bord (ex. Kibana) • Utilisez une API-KEY q ’ q Observabilité → Mieux anticiper le décommissionnement des versions dépréciées
43. • é é à … • Publiez votre roadmap et changelogs régulièrement • Indiquez dans les headers de vos réponses que votre API est dépréciée Communication Deprecation: version="v1" Link:https://developer.example.com/deprecation
44. Code First / API First
45. Création de ’ • Spécifications • Création des controllers Java Documentation via des annotations • SpringDoc • Microprofile OpenAPI Génération de ’O Code First
46. Création de ’ • Création ’ fichier de description OPENAPI qui sert de spécification Génération du code • Héritage pour specifier le code spécifique des controllers • Validation du contrat de service par la compilation Construction des livrables API First
47. Les limites “C F ” ? Points négatifs • Les fichiers OpenAPI généréspeuvent ne pas être valides • Nécessite un grand nombre ’ à ajouter • Définir une API en avance de phase peut être fastidieux Points positifs • La mise en oeuvre est “ ” APIs
48. • Aucun décalage avec la spécification • La validation est faite par la compilation • Nécessite ’ de la spécification OPENAPI • Nécessite un outillage et un processus API First: Une solution?
49. • Les fichiers OPENAPI sont centralisés dans un repository GIT • La validation se fait par revue lors des Merge Requests Un repository GIT
50. Validation https://pb33f.io/doctor/ https://quobix.com/vacuum/
51. Génération du code avec Gradle (ou Maven) openapi-generator.tech
52. La sécurité
53. Les modèles ’ à ’é du versioning
54. La V1 de la policy (avec un modèle RBAC) Bookstore admin Bookstore customer Utilisateurs Rôles Permissions Books/write Books/search Isbns/read Isbns/write Books/read Admin Recherche Consultation
56. Une nouvelle policy (V2) Bookstore Admin Bookstore customer Utilisateurs Rôles Permissions Books/search Isbns/read Books/write Isbns/write Books/read Authors/write Gestion auteurs admin recherche
59. Exemple avec des scopes
60. On peut avoir des changements bloquants dans les policies ! Selon les outils (ex. CASBIN, Keycloak …) hésiter à les versionner! En é é… BookAdmin_V1
61. Conclusion
62. Pour vos prochaines APIs Evitez dans un premier temps Identifiez les breaking changes Travaillez sur la modularité des APIs Observez! Pensez le versioning de manière globale Communiquez!
63. Pour aller plus loin https://github.com/alexandre-touret/rest-apis-versioning-workshop https://github.com/alexandre-touret/rest-apis-versioning-solution https://blog.touret.info/en/2023/03/27/rest-api-versioning/ https://docs.github.com/en/rest/overview/api-versions
64. D ’ ! Follow & get in touch @touret_alex linkedin.com/in/atouret blog.worldline.tech @WorldlineTech Follow our tech team: Follow me: blog.touret.info
65. Explore our jobs in tech: careers.worldline.com Want to shape how the world pays and get paid?