Le Guide API ReST | Marmicode
  • Le Guide API ReST par Marmicode
  • API ReST
    • L'Ecosystème Moderne
    • Le Besoin
    • Re.S.T. : REpresentational State Transfer
    • Les 5 règles et ½ de l’API ReST
    • Le Modèle de Maturité de Richardson
    • H.A.T.E.O.A.S. & Resource Linking
    • Avis Subjectif sur H.A.T.E.O.A.S. et le Semantic Web
    • ReST over HTTP
    • HTTP & CRUD
    • ReSTful donc Stateless
    • Pragmatisme, Idéologie et ReSTafarians
  • Conventions & Bonnes Pratiques
    • Nommage
    • Base URL
    • Media Type
    • Versioning
    • Propriété “id”
    • Polymorphisme
    • Datetime
    • Ressource d'Association
    • Pourquoi Appliquer ces Bonnes Pratiques
    • Zalando ReSTful API Guidelines
  • Les Outils
    • Swagger
    • OpenAPI Visual Editors
    • IDE Plugins
    • Postman
    • Insomnia
    • Fake & Sandbox
    • JSON Generator
    • Pact
  • Sécurité des APIs ReST
    • OWASP Top 10
    • Authentification et Session Management
    • Autorisation et Gestion des Permissions
    • Validation, Canonicalization, Escaping & Sanitization
    • Cookies are EVIL
    • C.O.R.S.
    • C.S.R.F.
    • C.S.R.F. & Media Type
    • C.S.R.F. Mitigation
    • C.S.R.F. & "Resource Linking"
    • J.O.S.E.
      • J.W.K.
      • J.W.S.
      • J.W.E.
    • J.W.T.
      • Description et Fonctionnement de JWT
      • Usages et Avantages
      • Utilisation de JWT pour l’Authentification
      • JWT, Authentification, Sessions et Risques Sécurité
      • Recommandations JWT
    • OAuth 2
      • OAuth 2 Roles
      • OAuth 2 Abstract Flow
      • OAuth 2 Authorization Code Flow
      • OAuth 2 Implicit Flow
      • OAuth 2 Resource Owner Password Credentials Flow
      • OAuth 2 Client Credentials
      • OAuth 2 Registration
      • OAuth 2 Risques & Recommandations
      • OAuth 2 Substitution Attack
    • OpenID Connect
      • Terminologie
      • Quoi de Neuf ?
      • OpenID Connect Flows
      • Que Faire ?
  • Autres Spécifications
    • JSON API
    • H.A.L.
    • JSON LD
    • Les Autres Initiatives
    • So What?
  • Quelques Liens & Ressources
  • Stay Tuned
    • 📝Blog
    • 🐦Twitter
    • 📬Newsletter
Propulsé par GitBook
Sur cette page
  • Versioning par Media Type
  • Versioning par URL
  1. Conventions & Bonnes Pratiques

Versioning

PrécédentMedia TypeSuivantPropriété “id”

Dernière mise à jour il y a 6 ans

Etant donné que les APIs ReST sont conçues pour être utilisées par de multiples sources (clients mobiles / web / desktop / partenaires / public…), elles évoluent souvent à un rythme différent de celui des clients.

Pour s'adapter au changement, il y a trois principales approches :

  • Versioning par Media Type.

  • Versioning par URL.

  • Pas de versioning (la solution à privilégier tant que possible).

Versioning par Media Type

Le versioning par Media Type consiste à utiliser le comportement standard des headers HTTP Accept et Content-Type.

Le client indique alors la version de l’API qu’il supporte dans le header Accept : Accept: application/vnd.wishtack.v3+json

L’API retourne alors les données dans la version correspondante avec le bon Media Type dans le header Content-Type.

  • Séduisant mais légèrement complexe à mettre en place.

  • Comment faire si la nouvelle version est implémentée dans un langage différent ou encore sur une plateforme différente ?

Versioning par URL

Vu l’obstacle de balancing posé par le versioning par Media Type, pourquoi ne pas utiliser un balancing standard en amont… mais lequel ?

Qui dit mieux ?

Nous serions alors obligé d’utiliser un connecteur pour effectuer le balancing.

Nous pourrions utiliser le path de l’URL et procéder au balancing en fonction du nom de domaine. Cela nécessite toujours un connecteur : mais c'est une approche un peu plus classique et plus facile à configurer.

Yes ! Le DNS ! NodeJS hosted on Amazon. Python hosted on Heroku. Python hosted on Heroku sur un monorépo avec l’API V2. Serverless functions sur un monorépo avec l’API V2 et V3.

https://github.com/Kong/kong/issues/402
https://getkong.org/docs/0.13.x/proxy/#request-path
https://v1.api.wishtack.com
https://v2.api.wishtack.com
https://v3.api.wishtack.com
https://v4.api.wishtack.com
https://blog.apisyouwonthate.com/api-versioning-has-no-right-way-f3c75457c0b7
API Versioning Has No "Right Way"
Logo