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

Quand on souhaite publier des APIs avec par exemple, une solution d'API Management, on évoque régulièrement le versioning. Cette pratique répond à des contraintes projet mais apporte malheureusement son lot de complexité.

Imaginez, vous travaillez sur un produit qui expose des APIs à plusieurs clients. Vous devez leur proposer des évolutions et nouvelles fonctionnalités tout en maîtrisant l'existant.
Quelle stratégie adopter ? Quelles solutions techniques peut-on mettre en place simplement ?

Dans cette présentation, vous (re)découvrirez des conseils que j'ai pu mettre en pratique et qui m'ont aidé lors de mes derniers projets.

Nous aborderons, au travers d'un cas concret la stratégie à mettre en œuvre, les différentes possibilités d'implémentation ainsi que leurs contraintes.

À l’issue de cette présentation, nous aurons une vue complète et objective des manières d'appréhender le versioning d'APIs.

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, Tech Rel @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. Identifier les changements bloquants https://www.oasdiff.com
28. La fonctionnalité majeure de la V2 Gestion ’ liste ’ V2 V1
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. La sécurité
45. Les modèles ’ à ’é du versioning
46. 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
48. 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
51. Exemple avec des scopes
52. On peut avoir des changements bloquants dans les policies ! Selon les outils (ex. CASBIN, Keycloak …) hésiter à les versionner! En é é… BookAdmin_V1
53. Conclusion
54. 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!
55. 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
56. D ’ ! Follow & get in touch @touret_alex linkedin.com/in/atouret blog.worldline.tech @WorldlineTech Follow our tech team: Follow me: blog.touret.info
57. Explore our jobs in tech: careers.worldline.com Want to shape how the world pays and get paid?