Eseguendo un'API, se correggo un'intestazione del tipo di contenuto, ciò spezzerà le cose per i clienti?

Stiamo eseguendo un'API con parecchie persone che la utilizzano. A causa di un po 'di goffaggine legacy da parte mia, uno degli endpoint sta restituendo l' intestazione del tipo di contenuto errata , jsquando dovrebbe essere json. La mia domanda è: se lo risolviamo scambiando per restituire il valore corretto, quanto male potrebbe rovinare le cose per i nostri clienti esistenti? O, per dirla in altro modo, ti aspetteresti che diverse librerie client HTTP generino errori fatali quando vedi un tale cambiamento?

Stiamo cercando di decidere se si tratta di un cambiamento che possiamo semplicemente procedere e apportare senza sudare troppo, oppure dovremmo inviare un'e-mail con attenzione a tutti gli utenti e annunciare un periodo di ammortamento pluriennale ... o qualcosa nel mezzo.

Probabilmente dipende un po 'dal tipo di client HTTP diversi in uso, quindi ho dato un'occhiata agli user agent. Risposta: molte diverse! Ecco alcuni dei migliori:

"okhttp / 3.2.0", "python-request / 2.10.0", "Ruby", "python-request / 2.7.0", "Mozilla / 5.0", "Java / 1.8.0_91", "python-request /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 / UNAVAILABLE "," Dalvik / 1.6.0 "," Web-sniffer / 1.1.0 "," unirest-objc / 1.1 "

Varie librerie di lingue lato mobile e lato server. Principalmente non i browser che eseguono JavaScript, ma anche alcuni di quelli.

La maggior parte delle persone non sembra notare che il tipo di contenuto sia sbagliato, ma ogni tanto viene visualizzata una nuova richiesta di supporto che si lamenta di questo problema, quindi vorremmo risolverlo.

quanto potrebbe rovinare le cose per i nostri clienti esistenti?

Potrebbe affondare completamente le loro navi da guerra se hanno scritto codice che si basa sul fatto che questo tipo di contenuto sia errato.

Non mi aspetto che le librerie generino errori, ma mi aspetto che in alcuni casi le librerie rigorose abbiano avuto il loro comportamento ignorato per gestire il tipo MIME errato.

Se l'API ha un valore di versione / revisione in un campo di richiesta da qualche parte, aumentalo e nella nuova versione restituisce il tipo corretto ma continua a restituire il tipo errato nelle versioni precedenti. Se non disponi di un campo di richiesta del genere, ora è il momento di aggiungerne uno.

Ti aspetteresti che diverse librerie client HTTP generino errori fatali quando vedrai un tale cambiamento?

No. Ogni libreria client HTTP che conosco ignorerà l'intestazione del tipo di contenuto a meno che il programmatore non legga espressamente quell'intestazione e faccia qualcosa con essa. Posso immaginare una libreria in cui il tipo di contenuto: application / json provoca automaticamente il coinvolgimento di un parser json ma non conosco alcun caso in cui ciò avvenga effettivamente.

La maggior parte delle persone non sembra notare che il tipo di contenuto sia sbagliato, ma ogni tanto viene visualizzata una nuova richiesta di supporto che si lamenta di questo problema, quindi vorremmo risolverlo.

Come hanno notato l'intestazione errata? Potrebbe valere la pena guardarlo, perché se l'intestazione errata stava effettivamente causando loro problemi, chiaramente non lo stavano semplicemente ignorando, e potrebbero avere problemi se fosse risolto.

Troppo difficile da dire senza ottenere l'approvazione da tutti i tuoi clienti. Suggerirei di adottare uno dei due seguenti approcci per aggiornare l'API a v.Next.

1. Estendi l'API esistente. Aggiungi una stringa di query o qualche altra variabile all'API che significa utilizzare v.Next. Per tutte le richieste che utilizzano quella variabile, utilizzare il tipo di contenuto aggiornato.
2. Esegui un'istanza di staging o pre-produzione dell'API in parallelo con l'API corrente. Dovrebbe essere quasi identico alla produzione. Anche usando lo stesso back-end. Anche se questo avrà le modifiche proposte per v.Next.

In entrambi gli scenari, comunica ai tuoi clienti le modifiche che desideri apportare e la data / ora del ritaglio target. Incoraggiali a testare molto prima della data prevista per assicurarsi che non vi siano interruzioni del servizio.

Assicurati di avere una pagina dedicata che descriva in dettaglio le modifiche apportate a v.Prossimo. Questo dovrebbe essere incluso nelle comunicazioni inviate ai tuoi clienti. Se hai discusso di eventuali correzioni con client esistenti, includi quelli in questa pagina.

Infine, fai un passo avanti tra comunicazione eccessiva con i tuoi clienti e spamming. Queste notifiche possono essere facilmente ignorate quando emergono priorità più immediate / urgenti.

FWIW, se le cose stanno funzionando non mi preoccuperei troppo. Se, ad esempio, scopri che ciò causa una significativa vulnerabilità della sicurezza, questa sarebbe un'ottima ragione per respingere questo cambiamento. Altrimenti aspetterei qualcosa di più urgente per includere questo cambiamento.

Ecco un esempio di una libreria (beh, singolo comando) che questo si romperà:

Il cmdlet PowerShellInvoke-RestMethod agisce in modo diverso con JSON. Se il risultato della richiesta è JSON, XML o ATOM / RSS (e penso che sia basato sull'intestazione), la analizza / deserializza e restituisce oggetti nativi, altrimenti restituisce i dati non elaborati.

Quindi il codice esistente verrebbe scritto per gestire una stringa (magari passandola a ConvertFrom-Json) e all'improvviso inizierebbe a fallire.

Ho notato due conseguenze:

1. Alcune librerie client non elaboreranno la risposta correttamente. Ad esempio, la risposta restituisce una stringa anziché json o un array.
2. La compressione non viene sempre applicata.