[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
   

   View Slide

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

   View Slide

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

   View Slide

4. Il était une fois une API…
   

   View Slide

5. View Slide

6. L’ API
   

   View Slide

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

   View Slide

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
   

   View Slide

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
   

   View Slide

10. View Slide

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

    View Slide

12. Avant tout ça … etou su la V1
    

    View Slide

13. L’ API V1
    

    View Slide

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
    

    View Slide

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

    View Slide

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

    View Slide

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
    

    View Slide

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 ?
    

    View Slide

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

    View Slide

20. Ajout ’o é ations et données
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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?
    

    View Slide

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

    View Slide

25. View Slide

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

    View Slide

27. View Slide

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

    View Slide

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

    View Slide

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
    

    View Slide

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
    

    View Slide

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?
    

    View Slide

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

    View Slide

34. View Slide

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

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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?
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

44. La sécurité
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

51. Exemple avec des scopes
    

    View Slide

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
    

    View Slide

53. Conclusion
    

    View Slide

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!
    

    View Slide

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
    

    View Slide

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

    View Slide

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
    

    View Slide

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

    View Slide