Запустив API, если я исправлю заголовок типа контента, это сломает вещи для клиентов?

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

Мы пытаемся решить, является ли это изменение, которое мы можем просто сделать и не потревожить его, или мы должны тщательно отправить электронное письмо всем пользователям и объявить многолетний период амортизации ... или что-то среднее.

Вероятно, это немного зависит от того, какие разные HTTP-клиенты используются, поэтому я взглянул на пользовательских агентов. Ответ: много разных! Вот некоторые из лучших:

"okhttp / 3.2.0", "python-запросы / 2.10.0", "Ruby", "python-запросы / 2.7.0", "Mozilla / 5.0", "Java / 1.8.0_91", "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 / UNAVAILABLE "," Dalvik / 1.6.0 "," Web-sniffer / 1.1.0 "," unirest-objc / 1.1 "

Различные библиотеки для мобильных и серверных языков. В основном это не браузеры с javascript, но некоторые из них тоже.

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

насколько сильно это может испортить ситуацию для наших существующих клиентов?

Это могло бы полностью потопить их линкоры, если бы они написали код, основанный на неверном типе контента .

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

Если у вашего API есть где-то значение версии / ревизии в поле запроса, поднимите его и в новой версии верните правильный тип, но продолжайте возвращать неправильный тип в более старых версиях. Если у вас нет такого поля запроса, сейчас самое время добавить его.

Ожидаете ли вы, что многие другие клиентские библиотеки HTTP будут вызывать фатальные ошибки при появлении такого изменения?

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

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

Как они заметили неправильный заголовок? Возможно, стоит взглянуть на это, потому что, если неправильный заголовок действительно вызывает у них проблемы, они явно не просто игнорируют его, и у них могут быть проблемы, если он исправлен.

Слишком сложно сказать, не получив одобрения от всех ваших клиентов. Я бы предложил использовать один из следующих двух подходов для обновления вашего API до v.Next.

1. Расширить существующий API. Добавьте строку запроса или некоторую другую переменную в ваш API, которая означает использование v.Next. Для всех запросов, использующих эту переменную, используйте обновленный тип содержимого.
2. Запустите Staging или Pre-Production экземпляр вашего API параллельно с вашим текущим API. Это должно быть почти идентично производству. Даже используя тот же бэкэнд. Хотя этот будет иметь предлагаемые изменения для v.Next.

В любом случае сообщайте своим клиентам об изменениях, которые вы хотите внести, и целевую дату / время перехода. Поощряйте их тестировать задолго до установленной даты, чтобы убедиться, что сервис не прерывается.

Убедитесь, что у вас есть специальная страница с подробным описанием изменений, внесенных в v.Next. Это должно быть включено в сообщения, рассылаемые вашим клиентам. Если вы обсуждали какие-либо исправления с существующими клиентами, включите их на этой странице.

Наконец, проведите грань между чрезмерным общением с вашими клиентами и рассылкой спама. Эти уведомления могут быть легко пропущены по мере появления более неотложных / неотложных приоритетов.

FWIW, если вещи в настоящее время работают, я бы не слишком беспокоился об этом. Если, например, вы обнаружите, что это приводит к значительной уязвимости в системе безопасности, это было бы отличной причиной для устранения этого изменения. В противном случае я бы подождал, пока что-то более неотложное, чтобы включить это изменение

Вот пример библиотеки (ну, единственная команда), которая сломается:

PowerShell Командлет Invoke-RestMethodдействует по- разному с JSON. Если результатом запроса является JSON, XML или ATOM / RSS (и я думаю, что он основан на заголовке), он анализирует / десериализует его и возвращает собственные объекты, в противном случае он возвращает необработанные данные.

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

Я заметил два последствия:

1. Некоторые клиентские библиотеки не будут правильно обрабатывать ответ. Например, ответ возвращает строку вместо json или массив.
2. Сжатие не всегда применяется.