4.16. Permettre le versionnage et l'évolution

4.16. Permettre le versionnage et l'évolution

L'un des aspects les plus difficiles de la conception d'un protocole d'application est de s'assurer qu'il peut évoluer au fil du temps tout en maintenant la compatibilité avec les déploiements existants.

Les applications utilisant HTTP DEVRAIENT concevoir pour l'extensibilité dès le début. Cela inclut:

• Négociation de protocole: Fournir des mécanismes permettant aux clients et aux serveurs de négocier quelle version ou quelles fonctionnalités utiliser.

• Dégradation gracieuse: Permettre aux anciens clients de fonctionner avec de nouveaux serveurs (et vice versa), même s'ils ne prennent pas en charge toutes les fonctionnalités.

• Découverte de fonctionnalités: Permettre aux clients de découvrir quelles fonctionnalités un serveur prend en charge.

• Ignorer les éléments inconnus: Spécifier que les implémentations devraient ignorer les champs d'en-tête, le contenu ou d'autres éléments de protocole inconnus plutôt que de les traiter comme des erreurs.

Les approches courantes du versionnage incluent:

• Versionnage par type de média: Utiliser différents types de médias pour différentes versions (par exemple, application/vnd.example.v1+json, application/vnd.example.v2+json).

• Versionnage par URL: Inclure la version dans l'URL (par exemple, /v1/resource, /v2/resource). Cependant, cela peut créer des problèmes avec la mise en cache et l'identité des ressources.

• Versionnage par champ d'en-tête: Utiliser un champ d'en-tête personnalisé pour indiquer la version.

• Négociation basée sur les fonctionnalités: Plutôt que de versionner l'ensemble du protocole, permettre la négociation de fonctionnalités individuelles.

Les applications DEVRAIENT:

• Documenter clairement comment fonctionne le versionnage.

• Fournir des conseils sur la façon de maintenir la rétrocompatibilité.

• Considérer l'impact du versionnage sur la mise en cache et d'autres fonctionnalités HTTP.

• Éviter de faire des changements incompatibles avec les versions existantes; définir plutôt de nouvelles versions lorsque des changements incompatibles sont nécessaires.

Les applications NE DEVRAIENT PAS:

• Utiliser des paramètres de requête URL pour le versionnage, car cela peut interférer avec la mise en cache.

• Créer des situations où différentes versions du protocole utilisent les mêmes identifiants (URL, types de médias) pour différentes choses.

• Forcer les clients à mettre à jour immédiatement lorsque de nouvelles versions sont publiées.