Le versioning des APIs REST Dans la vraie vie, on fait comment? Alexandre TOURET DevFestLille

Alexandre TOURET Architecte logiciel @touret_alex blog.touret.info alexandre-touret Qui suis-je?

We design payments technology that powers the growth of millions of businesses around the world. Who are we?

Il était une fois une API…

No content

L’ API

Le workshop https://github.com/alexandre-touret/rest-apis-versioning-workshop https://github.com/alexandre-touret/rest-apis-versioning-solution

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

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

No content

Delivery CI/CD Organisation du code Sécurité Compatibilité ascendante Impacts

Avant tout ça … etou su la V1

L’ API V1

• 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

Une version dépréciée Une version courante Combien de versions concurrentes?

Qu’est- e qu’on e sionne ? On versionne les changements bloquants sur le contrat de services (opérations ou données)

✓ 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

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 ?

Des changements non bloquants? Les changements non bloquants peuvent être ajoutés sans versioning

Ajout ’o é ations et données

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

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

é 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?

Positionner une version dans l’URI Si vous voulez repousser l’utilisation du versioning /v1/api/books

No content

Un nouveau client et de nouvelles fonctionnalités (V2)

No content

La fonctionnalité majeure de la V2 Gestion ’ liste ’ V2 V1

Contrat de services Bases de données Compatibilité avec la V1 Impacts

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

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

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?

De l’o anisation u o e à la mise en production

No content

Main Feature Hotfix Develop Release V1 V2 V2.1 Release avec la liste des auteurs Compatibilité ascendante V1.1

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

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

• 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

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

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?

├── 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

• 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

• 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

La sécurité

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

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

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

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

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

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

Exemple avec des scopes

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

Conclusion

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!

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

https://bit.ly/apiversioning2305 Merci! ’ é à !

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

Explore our jobs in tech: careers.worldline.com Want to shape how the world pays and get paid?