Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

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

Alexandre Touret

May 30, 2024
Tweet

More Decks by Alexandre Touret

Other Decks in Programming

Transcript

  1. Le versioning des APIs REST Dans la vraie vie, on

    fait comment? Alexandre TOURET
  2. 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
  3. • 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
  4. Q ’ - q ’ ? On versionne les changements

    bloquants sur le contrat de services (opérations ou données)
  5. ✓ 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
  6. Une modification bloquante dans le contrat de services Par exemple

    : dans notre objet Book un auteur devient une liste ’ C’ -à-dire ? Q ’ - q ’ q ?
  7. 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
  8. é ’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?
  9. Main Feature Hotfix Develop Release V1 V2 V2.1 Release avec

    la liste des auteurs Compatibilité ascendante V1.1
  10. 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
  11. • 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
  12. • U ’ exécution par version • Centralisez la gestion

    des versions par une API Gateway L ’ é
  13. 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?
  14. ├── │ └── 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
  15. • 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
  16. • é é à … • 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
  17. Création de ’ • Spécifications • Création des controllers Java

    Documentation via des annotations • SpringDoc • Microprofile OpenAPI Génération de ’O Code First
  18. 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
  19. 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
  20. • 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?
  21. • Les fichiers OPENAPI sont centralisés dans un repository GIT

    • La validation se fait par revue lors des Merge Requests Un repository GIT
  22. 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
  23. 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
  24. On peut avoir des changements bloquants dans les policies !

    Selon les outils (ex. CASBIN, Keycloak …) hésiter à les versionner! En é é… BookAdmin_V1
  25. 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!
  26. D ’ ! Follow & get in touch @touret_alex linkedin.com/in/atouret

    blog.worldline.tech @WorldlineTech Follow our tech team: Follow me: blog.touret.info