Exécuter une API, si je corrige un en-tête de type de contenu, est-ce que cela cassera les choses pour les clients?

Nous exécutons une API avec un bon nombre de personnes l'utilisant. En raison d'une certaine maladresse héritée de ma part, l'un des points de terminaison renvoie le mauvais en-tête de type de contenu , jsalors qu'il devrait l'être json. Ma question est, si nous corrigeons cela en échangeant pour retourner la valeur correcte, à quel point cela pourrait-il gâcher les choses pour nos clients existants? Ou, pour le dire autrement, vous attendriez-vous à ce que de nombreuses bibliothèques client HTTP différentes génèrent des erreurs fatales en voyant un tel changement?

Nous essayons de décider s'il s'agit d'un changement que nous pouvons simplement faire sans trop transpirer, ou nous devons envoyer un e-mail à tous les utilisateurs et annoncer une période de dépréciation de plusieurs années ... ou quelque chose entre les deux.

Cela dépend probablement un peu du type de différents clients HTTP utilisés, j'ai donc examiné les agents utilisateurs. Réponse: beaucoup de différents! Voici quelques-uns des meilleurs:

"okhttp / 3.2.0", "demandes-python / 2.10.0", "Ruby", "demandes-python / 2.7.0", "Mozilla / 5.0", "Java / 1.8.0_91", "demandes-python /2.4.3 "," okhttp / 3.3.0 "," Lucee "," Dalvik / 2.1.0 "," Google-HTTP-Java-Client / 1.21.0 "," PHP_appname "," NativeHost "," Java /1.7.0_67 "," Apache-HttpClient / INDISPONIBLE "," Dalvik / 1.6.0 "," Web-sniffer / 1.1.0 "," unirest-objc / 1.1 "

Différentes bibliothèques de langues côté mobile et côté serveur. Surtout pas les navigateurs exécutant javascript, mais certains d'entre eux aussi.

La plupart des gens ne semblent pas remarquer que le type de contenu est incorrect, mais de temps en temps une nouvelle demande d'assistance apparaît pour se plaindre de ce problème, nous aimerions donc y remédier.

à quel point cela pourrait-il gâcher les choses pour nos clients existants?

Cela pourrait complètement couler leurs cuirassés s'ils ont écrit du code qui repose sur ce type de contenu incorrect.

Je ne m'attendrais pas à ce que les bibliothèques génèrent des erreurs, mais je m'attends à ce que dans certains cas, les bibliothèques strictes aient vu leur comportement remplacé pour gérer le type MIME incorrect.

Si votre API a une valeur de version / révision quelque part dans un champ de requête, augmentez-la et, dans la nouvelle version, retournez le type correct mais continuez à renvoyer le type incorrect dans les anciennes versions. Si vous n'avez pas un tel champ de demande, c'est le bon moment pour en ajouter un.

Vous attendriez-vous à ce que de nombreuses bibliothèques client HTTP différentes génèrent des erreurs fatales en voyant un tel changement?

Non. Chaque bibliothèque client HTTP que je connais ignorera l'en-tête de type de contenu, sauf si le programmeur lit spécifiquement cet en-tête et en fait quelque chose. Je peux imaginer une bibliothèque où le type de contenu: application / json entraîne automatiquement l'implication d'un analyseur json mais je ne connais aucun cas où cela se produit réellement.

La plupart des gens ne semblent pas remarquer que le type de contenu est incorrect, mais de temps en temps une nouvelle demande d'assistance apparaît pour se plaindre de ce problème, nous aimerions donc y remédier.

Comment ont-ils remarqué l'en-tête incorrect? Cela vaut peut-être la peine de l'examiner, car si l'en-tête incorrect leur causait effectivement des problèmes, ils ne l'ignoraient pas simplement, et ils pourraient avoir des problèmes s'il était corrigé.

Trop difficile à dire sans obtenir l'approbation de tous vos clients. Je suggère de prendre l'une des deux approches suivantes pour mettre à niveau votre API vers v.Next.

1. Étendez l'API existante. Ajoutez une chaîne de requête ou une autre variable à votre API qui signifie utiliser v.Next. Pour toutes les demandes utilisant cette variable, utilisez le type de contenu mis à jour.
2. Exécutez une instance de préparation ou de pré-production de votre API en parallèle avec votre API actuelle. Elle devrait être presque identique à la production. Même en utilisant le même back-end. Bien que celui-ci contienne les modifications proposées pour v.Next.

Dans les deux cas, communiquez à vos clients les modifications que vous souhaitez apporter et la date / heure de basculement cible. Encouragez-les à effectuer des tests bien avant la date cible pour s'assurer qu'il n'y a pas d'interruption de service.

Assurez-vous d'avoir une page dédiée détaillant les modifications apportées à v.Next. Cela devrait être inclus dans les communications envoyées à vos clients. Si vous avez discuté de correctifs avec des clients existants, incluez-les sur cette page.

Enfin, suivez la ligne entre la communication excessive avec vos clients et le spam. Ces notifications peuvent être facilement ignorées lorsque des priorités plus immédiates / urgentes se présentent.

FWIW, si les choses fonctionnent actuellement, je ne m'en inquiéterais pas trop. Si, par exemple, vous constatez que cela entraîne une vulnérabilité de sécurité importante, ce serait une excellente raison de pousser ce changement. Sinon, j'attendrais quelque chose de plus urgent pour inclure ce changement.

Voici un exemple de bibliothèque (enfin, commande unique) que cela casserait:

L' applet de commande PowerShellInvoke-RestMethod agit différemment avec JSON. Si le résultat de la demande est JSON, XML ou ATOM / RSS (et je pense qu'il est basé sur l'en-tête), il l'analyse / désérialise et renvoie des objets natifs, sinon il renvoie les données brutes.

Ainsi, le code existant serait écrit pour gérer une chaîne (peut-être en le passant à ConvertFrom-Json) et échouerait soudainement.

J'ai remarqué deux conséquences:

1. Certaines bibliothèques clientes ne traiteront pas correctement la réponse. Par exemple, la réponse renvoie une chaîne au lieu de json ou d'un tableau.
2. La compression n'est pas toujours appliquée.