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 full-size slide

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

    View full-size slide

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

    View full-size slide

  4. Il était une fois une API…

    View full-size slide

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

    View full-size slide

  6. 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 full-size slide

  7. 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 full-size slide

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

    View full-size slide

  9. Avant tout ça … etou su la V1

    View full-size slide

  10. • 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 full-size slide

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

    View full-size slide

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

    View full-size slide

  13. ✓ 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 full-size slide

  14. 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 full-size slide

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

    View full-size slide

  16. Ajout ’o é ations et données

    View full-size slide

  17. 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 full-size slide

  18. 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 full-size slide

  19. é 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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  24. 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 full-size slide

  25. 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 full-size slide

  26. 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 full-size slide

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

    View full-size slide

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

    View full-size slide

  29. 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 full-size slide

  30. 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 full-size slide

  31. • 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 full-size slide

  32. 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 full-size slide

  33. 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 full-size slide

  34. ├── 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 full-size slide

  35. • 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 full-size slide

  36. • 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 full-size slide

  37. La sécurité

    View full-size slide

  38. 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 full-size slide

  39. 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 full-size slide

  40. 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 full-size slide

  41. 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 full-size slide

  42. 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 full-size slide

  43. 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 full-size slide

  44. Exemple avec des scopes

    View full-size slide

  45. 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 full-size slide

  46. 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 full-size slide

  47. 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 full-size slide

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

    View full-size slide

  49. 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 full-size slide

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

    View full-size slide