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

Slide 1

Slide 1 text

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

Slide 2

Slide 2 text

No content

Slide 3

Slide 3 text

L’ API

Slide 4

Slide 4 text

La vue haut niveau

Slide 5

Slide 5 text

Sous le capot

Slide 6

Slide 6 text

No content

Slide 7

Slide 7 text

Let's version this API

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

Avant tout ça … V1

Slide 12

Slide 12 text

L’ API V1

Slide 13

Slide 13 text

• 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

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

Q ’ - q ’ ? On versionne les changements bloquants sur le contrat de services (opérations ou données)

Slide 16

Slide 16 text

✓ 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

Slide 17

Slide 17 text

Une modification bloquante dans le contrat de services Par exemple : dans notre objet Book un auteur devient une liste ’ C’ -à-dire ? Q ’ - q ’ q ?

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

Ajout ’ é et données

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

No content

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

Positionner une version dans ’UR Si vous voulez repousser ’ du versioning /v1/api/books

Slide 24

Slide 24 text

No content

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

No content

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

Identifier les changements bloquants https://www.oasdiff.com

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

V2 V1 V2 V1

Slide 31

Slide 31 text

Quid de la base de données (relationnelle)? L V2 V1

Slide 32

Slide 32 text

Deux bases de données?

Slide 33

Slide 33 text

D ’ à la mise en production

Slide 34

Slide 34 text

No content

Slide 35

Slide 35 text

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

Slide 36

Slide 36 text

Gestion de la configuration

Slide 37

Slide 37 text

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

Slide 38

Slide 38 text

• 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

Slide 39

Slide 39 text

• U ’ exécution par version • Centralisez la gestion des versions par une API Gateway L ’ é

Slide 40

Slide 40 text

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?

Slide 41

Slide 41 text

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

Slide 42

Slide 42 text

• 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

Slide 43

Slide 43 text

• é é à … • 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

Slide 44

Slide 44 text

Code First / API First

Slide 45

Slide 45 text

Création de ’ • Spécifications • Création des controllers Java Documentation via des annotations • SpringDoc • Microprofile OpenAPI Génération de ’O Code First

Slide 46

Slide 46 text

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

Slide 47

Slide 47 text

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

Slide 48

Slide 48 text

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

Slide 49

Slide 49 text

• Les fichiers OPENAPI sont centralisés dans un repository GIT • La validation se fait par revue lors des Merge Requests Un repository GIT

Slide 50

Slide 50 text

Validation https://pb33f.io/doctor/ https://quobix.com/vacuum/

Slide 51

Slide 51 text

Génération du code avec Gradle (ou Maven) openapi-generator.tech

Slide 52

Slide 52 text

La sécurité

Slide 53

Slide 53 text

Les modèles ’ à ’é du versioning

Slide 54

Slide 54 text

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

Slide 55

Slide 55 text

No content

Slide 56

Slide 56 text

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

Slide 57

Slide 57 text

No content

Slide 58

Slide 58 text

No content

Slide 59

Slide 59 text

Exemple avec des scopes

Slide 60

Slide 60 text

On peut avoir des changements bloquants dans les policies ! Selon les outils (ex. CASBIN, Keycloak …) hésiter à les versionner! En é é… BookAdmin_V1

Slide 61

Slide 61 text

Conclusion

Slide 62

Slide 62 text

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!

Slide 63

Slide 63 text

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

Slide 64

Slide 64 text

D ’ ! Follow & get in touch @touret_alex linkedin.com/in/atouret blog.worldline.tech @WorldlineTech Follow our tech team: Follow me: blog.touret.info

Slide 65

Slide 65 text

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