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

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

[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.

Alexandre Touret

May 26, 2023
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
    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