[DFL23]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 oeuvre, les différentes possibilités d'implémentation ainsi que leurs contraintes.

A 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 DevFestLille
2. Alexandre TOURET Architecte logiciel @touret_alex blog.touret.info alexandre-touret Qui suis-je?
3. We design payments technology that powers the growth of millions of businesses around the world. Who are we?
4. Il était une fois une API…
6. L’ API
7. Le workshop https://github.com/alexandre-touret/rest-apis-versioning-workshop https://github.com/alexandre-touret/rest-apis-versioning-solution
8. La vue haut niveau Allo s oo eation sea Allo s I entifi ation aut o i ation A usto e of t e oo sto e An a inist ato of t e oo sto e
9. Sous le capot oses t e oo sto e APIs oses t e APIs to es oo sto e oses t e I APIs oses t e onfi u ation at e s an o i es ist i ute t a in A usto e of t e oo sto e An a inist ato of t e oo sto e
11. Delivery CI/CD Organisation du code Sécurité Compatibilité ascendante Impacts
12. Avant tout ça … etou su la V1
13. L’ API V1
14. • Est- e que j’en ai esoin ? • 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
15. Une version dépréciée Une version courante Combien de versions concurrentes?
16. Qu’est- e qu’on e sionne ? On versionne les changements bloquants sur le contrat de services (opérations ou données)
17. ✓ 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
18. Une modification bloquante dans le contrat de services Par exemple : dans notre objet Book un auteur devient une liste ’ C’est-à-dire ? Q ’ - q ’ q ?
19. Des changements non bloquants? Les changements non bloquants peuvent être ajoutés sans versioning
20. Ajout ’o é ations et données
21. 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. oses t e oo sto e APIs oses t e APIs to es oo sto e oses t e I APIs oses t e onfi u ation at e s an o i es ist i ute t a in A usto e of t e oo sto e An a inist ato of t e oo sto e
23. é ifi ation e la e sion ans l’URL Le changement de version représente des changements bloquants é ifi ation e la e sion ans l’URL Ils sont toujou s à la V1… Spécification de la version dans le header "X-GitHub-Api-Version” Et les grands du web?
24. Positionner une version dans l’URI Si vous voulez repousser l’utilisation du versioning /v1/api/books
26. Un nouveau client et de nouvelles fonctionnalités (V2)
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. oses t e oo sto e APIs oses t e oo sto e APIs oses t e APIs to es oo sto e oses t e I APIs oses t e onfi u ation at e s an o i es ist i ute t a in A usto e of t e oo sto e An a inist ato of t e oo sto e V2 V1 V2 V1
31. oo t in aut o Quid de la base de données (relationnelle)? oo List Aut o aut o s Aut o t in fi stna e t in lastna e n V2 V1
32. oses t e oo sto e APIs oses t e oo sto e APIs oses t e APIs to es oo sto e to es oo sto e oses t e I APIs oses t e onfi u ation at e s an o i es ist i ute t a in A usto e of t e oo sto e An a inist ato of t e oo sto e Deux bases de données?
33. De l’o anisation u o e à 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. oses t e oo sto e APIs oses t e oo sto e APIs oses t e APIs to es oo sto e oses t e I APIs oses t e onfi u ation at e s an o i es ist i ute t a in A usto e of t e oo sto e An a inist ato of t e oo sto e 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. oses t e oo sto e APIs oses t e oo sto e APIs oses t e APIs • Un en i onne ent ’ exécution par version • Centralisez la gestion des versions par une API Gateway Les en i onne ents ’e é ution
40. oses t e oo sto e APIs oses t e APIs ansfo s ol equests es onses to ne ones • L’API ate ay e ose les eu versions (V1 et V2) • Elle transforme les requêtes et réponses de la V1 au format V2 Et si on ne gardait qu’un service?
41. ├── info │ └── touret │ └── oo sto e │ └── s in │ ├── oo │ │ ├── ont olle 1 │ │ ├── ont olle 2 │ │ ├── dto │ │ ├── entity │ │ ├── e e tion │ │ ├── a e │ │ ├── e osito y │ │ └── se i e Gérer les versions dans la base de code: 1 version = 1 package Une autre manière de faire ├── info │ └── touret │ └── oo sto e 1 │ └── oo sto e 2
42. • Identifiez qui utilise chaque version de votre API • Mettez en place des tableaux de bord (ex. Kibana) • Utilisez une API-KEY qui e ett a ’i entifie aque lient Observabilité → Mieux anticiper le décommissionnement des versions dépréciées
43. • P ésente ot e st até ie à os a tenai es … et en inte ne • 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 ’ a ilitation à l’é eu e du versioning Allo s oo eation sea Allo s I entifi ation aut o i ation A usto e of t e oo sto e An a inist ato of t e oo sto e
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
47. oses t e oo sto e APIs oses t e oo sto e APIs oses t e APIs to es oo sto e oses t e I APIs oses t e onfi u ation at e s an o i es ist i ute t a in A usto e of t e oo sto e An a inist ato of t e oo sto e
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
49. oses t e oo sto e APIs oses t e oo sto e APIs oses t e APIs to es oo sto e oses t e I APIs oses t e onfi u ation at e s an o i es ist i ute t a in A usto e of t e oo sto e An a inist ato of t e oo sto e
50. oses t e oo sto e APIs oses t e oo sto e APIs oses t e APIs to es oo sto e to es oo sto e oses t e I APIs oses t e onfi u ation at e s an o i es ist i ute t a in A usto e of t e oo sto e An a inist ato of t e oo sto e
51. Exemple avec des scopes
52. On peut avoir des changements bloquants dans les policies ! Selon les outils (ex. CASBIN, Keycloak …) ne as hésiter à les versionner! En ésu é… 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. https://bit.ly/apiversioning2305 Merci! ’ é à !
57. Don’t e a st an e ! Follow & get in touch @touret_alex linkedin.com/in/atouret blog.worldline.tech @WorldlineTech Follow our tech team: Follow me: blog.touret.info
58. Explore our jobs in tech: careers.worldline.com Want to shape how the world pays and get paid?