Запускаючи API, якщо я виправляю заголовок типу вмісту, це порушить справи для клієнтів?

У нас працює API з ним досить мало людей. Через деяку незграбність з мого боку, одна з кінцевих точок повертає неправильний заголовок типу вмісту , jsколи це має бути json. Моє запитання полягає в тому, що якщо ми вирішимо це шляхом заміни, щоб повернути правильне значення, наскільки погано це може зіпсувати речі для наших існуючих клієнтів? Або, кажучи іншим чином, чи очікуєте, що багато різних бібліотек клієнтів HTTP видають фатальні помилки, побачивши таку зміну?

Ми намагаємось вирішити, чи це зміна, яку ми можемо просто зробити вперед і зробити це не надто потужно, або нам слід обережно надіслати електронною поштою всім користувачам і оголосити багаторічний термін депресії ... або щось середнє.

Це, мабуть, трохи залежить від того, які різні клієнти HTTP використовуються, тому я роздивився агентів користувачів. Відповідь: дуже багато різних! Ось кілька найкращих:

"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 "

Різні різні бібліотеки мовної та серверної мови. Здебільшого це не браузери, на яких працює JavaScript, але деякі з них теж.

Більшість людей, здається, не помічають, що тип вмісту невірний, але раз у раз з’являється новий запит на підтримку, який скаржиться на цю проблему, тому ми хотіли б це виправити.

як погано це може зіпсувати речі для наших існуючих клієнтів?

Він може повністю затопити їх лінійні кораблі, якщо вони написали код, який покладається на те, що цей Content-Type є невірним.

Я б не очікував, що бібліотеки можуть видаляти помилки, але я вважаю, що в деяких випадках суворі бібліотеки перекривали свою поведінку для обробки неправильного типу MIME.

Якщо ваш API має значення версії / редакції десь у полі запиту, підніміть його, а в новій версії поверніть правильний тип, але продовжуйте повертати неправильний тип у старих версіях. Якщо у вас немає такого запиту, зараз прийшов час додати його.

Чи очікуєте ви, що багато різних бібліотек HTTP-клієнтів видаватимуть фатальні помилки, побачивши таку зміну?

Ні. Кожна бібліотека клієнтів HTTP, з якою я знайома, буде ігнорувати заголовок типу вмісту, якщо програміст спеціально не прочитає цей заголовок і щось з ним не зробить. Я можу уявити собі бібліотеку, в якій тип вмісту: application / json автоматично спричиняє участь аналізатора json, але я не знаю жодного випадку, коли це насправді відбувається.

Більшість людей, здається, не помічають, що тип вмісту невірний, але раз у раз з’являється новий запит на підтримку, який скаржиться на цю проблему, тому ми хотіли б це виправити.

Як вони помітили неправильний заголовок? Можливо, варто поглянути на це, адже якщо неправильний заголовок насправді спричиняє їм проблеми, вони, очевидно, не просто ігнорують його, і вони можуть мати проблеми, якщо це буде виправлено.

Занадто важко сказати, не виходячи з усіх своїх клієнтів. Я б запропонував скористатися одним із наступних двох підходів, щоб оновити API до v.Next.

1. Розширення існуючого API. Додайте рядок запиту або іншу змінну до свого API, що означає використовувати v.Next. Для всіх запитів, що використовують цю змінну, використовуйте оновлений тип вмісту.
2. Запустіть поетапний або передвиробничий екземпляр свого API паралельно з вашим поточним API. Він повинен бути майже ідентичним виробництву. Навіть використовуючи той самий бек-енд. Хоча в цьому буде запропоновані зміни для v.Next.

За будь-якого сценарію повідомте своїм клієнтам про зміни, які ви хочете внести, та цільову дату / час перерізу. Запропонуйте їм протестувати заздалегідь перед цільовою датою, щоб упевнитись у порушенні обслуговування.

Переконайтеся, що у вас є спеціальна сторінка з детальними відомостями про зміни, внесені до v.Next. Це повинно бути включено в повідомлення, що надсилаються вашим клієнтам. Якщо ви обговорювали будь-які виправлення з існуючими клієнтами, включіть їх на цю сторінку.

Нарешті, ступіть межу між надмірно спілкуватися зі своїми клієнтами та спамом. Ці сповіщення можна легко помітити, коли з’являються більш негайні / нагальні пріоритети.

FWIW, якщо справи зараз працюють, я б не переживав над цим. Якщо, наприклад, ви виявите, що це спричиняє значну вразливість безпеки, то це буде чудовим приводом витіснити цю зміну. Інакше я зачекаю на щось більш актуальне, щоб включити цю зміну.

Ось приклад бібліотеки (ну, одна команда), що це порушить:

PowerShell Командлети Invoke-RestMethodдіє по- різному з JSON. Якщо результатом запиту є JSON, XML або ATOM / RSS (і я думаю, що це базується на заголовку), він аналізує / десериалізує його та повертає рідні об'єкти, інакше повертає необроблені дані.

Таким чином, існуючий код буде написаний для обробки рядка (можливо, передавши його в ConvertFrom-Json), і раптом почав би виходити з ладу.

Я помітив два наслідки:

1. Деякі бібліотеки клієнтів не будуть обробляти відповідь належним чином. Наприклад, відповідь повертає рядок замість json або масиву.
2. Стиснення застосовується не завжди.