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?

14

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.

http http-headers

— Harry Wood
source

4

Je suppose que les clients qui fonctionnent correctement avec un en-tête de type de contenu incorrect ne cesseront pas de fonctionner une fois que vous aurez défini le bon, mais vous savez ce qu'ils disent des hypothèses. Alors testez, communiquez à l'avance vos modifications à votre base d'utilisateurs et / ou intégrez une logique supplémentaire que si un certain client tombe en panne, vous pouvez détecter ce client particulier et continuer à renvoyer l'en-tête de type de contenu incorrect (ou faire l'inverse, retourner le bon pour les clients qui génèrent des tickets de support et gardent la même chose pour les utilisateurs / agents utilisateurs actuels).

— HBruijn

5

xkcd obligatoire: xkcd.com/1172

— njzk2

N'êtes-vous pas en train de versionner votre API?

— Michael Hampton

Nous ne disposons que d'un numéro de version majeur pour l'ensemble de l'API que nous ne chercherons à contourner que dans quelques années lorsque nous effectuerons des restructurations assez importantes. À ce moment-là, nous réglerions ce problème bien sûr, mais ... on dirait que nous ne pourrons jamais le faire. C'est l'un de ces numéros de version.

— Harry Wood

30

à 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.

— alzee
source

6

+1 déjà pour une bonne hyperbole

— HBruijn

4

Souvent, vous n'avez pas le choix. Les clients qui reçoivent un ultimatum "mise à jour ou départ" peuvent décider de ce dernier, bon en principe, mauvais en pratique. L'ancienne version peut être retirée au fil du temps.

— alzee

3

+1 pour le versionnage des demandes, mais vous pouvez consulter en.wikipedia.org/wiki/Software_versioning pour plus d'informations.

— SBoss

7

@WinstonEwert: Bien sûr, cela en vaut la peine. Les gens spécifient la version d'API qu'ils souhaitent utiliser, puis leur programme ne brûle pas spontanément dans le temps entre la mise à jour de votre API et la mise à jour de leur programme. Si vous ne le faites pas, vous cassez automatiquement chaque version actuelle et historique du code de vos clients lorsque vous modifiez votre interface. Et c'est une façon affreuse de gérer un service.

— Courses de légèreté avec Monica

1

Cela semble être un très bon point en passant: "Je m'attends à ce que dans certains cas, les bibliothèques strictes aient eu leur comportement remplacé pour gérer le type MIME incorrect" Mon intuition (en réponse à toute la question) est que la grande majorité des clients les bibliothèques seront d'accord avec cela, mais c'est une préoccupation. Certains clients ont peut-être travaillé de manière proactive autour de cela, et l'échange les interrompra alors pour eux. Je me demande dans quelle mesure cela s'est produit.

— Harry Wood

11

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é.

— Winston Ewert
source

Ma réponse a un exemple où cela se produirait réellement .

— briantist

Si vous utilisez jQuery $.ajaxet ne spécifiez pas l' dataType:option, il déduit le type de réponse de l'en- Content-typetête. Donc, si c'est le cas application/json, il l'analysera automatiquement avant de le transmettre à l'appelant.

— Barmar

6

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.

É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.
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.

— user2320464
source

Merci. Ce n'est pas la réponse que je voulais entendre, mais vous avez peut-être raison. Nous devons simplement introduire le changement avec beaucoup de prudence. Est-ce que c'est trop difficile à dire? Je suppose que j'espérais que certaines personnes auraient l'expérience de l'impact probable de ce type particulier de changement d'en-tête de type de contenu (en laissant de côté les points plus génériques sur la gestion des versions avec prudence)

— Harry Wood

5

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

L' applet de commande PowerShell Invoke-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.

— briantiste
source

blogs.technet.microsoft.com/heyscriptingguy/2013/10/21/… confirme la théorie selon laquelle cela ressemble à l'en-tête.

— Winston Ewert

-2

J'ai remarqué deux conséquences:

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.
La compression n'est pas toujours appliquée.

— user368565
source

C'est sûrement celui qui envoie les données, pas celui qui les reçoit, qui applique la compression?

— TRiG