Stratégie de compatibilité d'APIet stratégies d'obsolescence

Stratégie de compatibilité

Compatibilité avec des versions antérieures ou modifications non essentielles

Ajout d'un URI de ressource pouvant étendre une ressource d'API existante

Cette modification est généralement sûre. Toutefois, elle doit prendre en compte les infrastructures client courantes qui peuvent générer du code entrant en conflit avec cette modification. Les exemples suivants sont des types de modifications à éviter, car elles peuvent altérer le code généré par le client.

• Une API existe dans /v1.0/foo/bar. Le générateur de code peut générer GetBar en tant que méthode client. /v1.0/foo/{param}Si une nouvelle API est introduite, où {param} est une chaîne de caractères arbitraire, le générateur de code pourrait générer la nouvelle méthode cliente sous la forme GetFoo(String param). Cette modification peut entraîner une modification majeure sur le client car la logique imbriquée dans GetBar n'est plus appelée.
• Un chemin en cours /v1.0/foo/bar peut générer le code client GetBar et GetBarAsync. L'ajout d'une API /v1.0/foo/Async entre en conflit avec ce code généré.

Ajout d'une méthode HTTP à une interface d'API

Cette modification est sûre à condition que le contenu de la demande avant cette modification continue d'exister et se comporte de la même manière. Une ou plusieurs zones facultatives peuvent être ajoutées au corps de demande d'une API existante ou en tant que paramètre de la chaîne de requête.

Ajout d'en-têtes de requête facultatifs

Cette modification est sûre à condition que la demande avant cette modification continue à répondre de la même manière.

Ajout d'une valeur autorisée à une propriété existante

Les modèles d'API utilisent des chaînes pour représenter des propriétés qui autorisent une liste contrainte de valeurs. Par exemple, type dans une ressource peut être documenté pour répertorier la liste en cours des types de ressource. Le client doit utiliser une chaîne générique pour ces types au lieu d'utiliser la désérialisation stricte d'un type enum bien défini. Une ressource qui accepte une propriété avec plusieurs valeurs possibles peut être optimisée pour autoriser davantage de valeurs. Ces nouvelles valeurs peuvent introduire les nouvelles propriétés et règles de validation correspondantes. Un client doit s'assurer qu'il ne valide pas des valeurs enum inexistantes, par exemple en exécutant une demande avec une valeur enum non valide et en attendant une réponse d'erreur.

Les valeurs de propriété existantes continuent à prendre en charge le comportement existant. Tout code client qui contient, par exemple, une logique de branchement sur le type de ressource continue à fonctionner comme avant.

Ajout de zones et/ou d'en-têtes facultatifs à une réponse

Les zones et les en-têtes facultatifs peuvent être ajoutés à une réponse d'API à tout moment. Le client doit s'adapter à de tels changements.

Modification d'un message d'erreur et de descriptions de ressources dans la réponse de l'API

La zone messageId dans une réponse d'erreur est considérée comme non modifiable et doit toujours couvrir la liste établie des cas ou conditions d'erreur. La description associée à ce message peut changer, sans modifier la signification sémantique du message pour un utilisateur.

Les clients ne doivent pas générer de logique basée sur l'attribut messageDescription.

Augmentation de la portée d'un ID de message d'erreur

La zone messageId fait référence à une ou plusieurs conditions d'erreur. Cette zone messageId peut être étendue pour couvrir davantage de conditions d'erreur à tout moment. Toutefois, une telle extension doit être logique et non arbitraire. Les nouvelles conditions d'erreur doivent être étroitement liées à une condition d'erreur existante qui est couverte par ce message.

En-têtes et erreurs de limite de débit

Les limites de débit peuvent être ajustées sur les noeuds finaux de l'API au cours de la durée de vie de l'API et ne nécessitent pas de mise à jour de version.

Les clients qui reçoivent le code de statut HTTP 429 correspondant à un nombre de demandes trop élevé doivent effectuer des ajustements.

Modifications majeures

Suppression ou changement de nom d'un noeud final de ressource d'API ou d'une méthode HTTP

Ce type de modification arrête tout client qui utilise l'API sans y être autorisé, à moins que la sécurité nécessite absolument cette modification. Tout est fait pour éviter un tel changement.

Suppression ou changement de nom des valeurs enum

Des valeurs pour enum peuvent être ajoutées mais pas supprimées.

Modifier le type type d'un champ

En général, le type d'une zone ne doit pas changer. Toutefois, si l'implémentation de l'API est en mesure d'accepter le type précédent et de répondre avec ce type, cette modification est considérée comme compatible avec les versions antérieures.

Modification du comportement visible des demandes existantes

Si une demande a précédemment généré une action ou une réponse spécifique, elle doit continuer à se comporter de cette manière. La seule exception concerne les extensions autorisées sur un contrat existant sous la forme de nouveaux messages d'erreur, de codes de statut HTTP et de zones de demande ou de réponse.

Stratégie d'obsolescence