У нас есть API, которым пользуется довольно много людей. Из-за моей устаревшей неуклюжести одна из конечных точек возвращает неправильный заголовок типа содержимого, js когда это должно быть json. У меня вопрос: если мы исправим это, заменив местами правильное значение, насколько сильно это может испортить ситуацию для наших существующих клиентов? Или, другими словами, ожидаете ли вы, что многие разные клиентские библиотеки HTTP будут выдавать фатальные ошибки, увидев такое изменение?
Мы пытаемся решить, является ли это изменение, которое мы можем просто пойти дальше и внести, не слишком запиваясь этим, или мы должны внимательно отправить всем пользователям электронное письмо и объявить о многолетнем периоде прекращения поддержки ... или что-то среднее.
Вероятно, это немного зависит от того, какие типы различных HTTP-клиентов используются, поэтому я взглянул на пользовательских агентов. Ответ: много разных! Вот некоторые из лучших:
«okhttp / 3.2.0», «python-requests / 2.10.0», «Ruby», «python-requests / 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 / НЕДОСТУПЕН "," Dalvik / 1.6.0 "," Веб-сниффер / 1.1.0 "," unirest-objc / 1.1 "
Различные библиотеки для мобильных и серверных языков. В основном это не браузеры с javascript, но некоторые из них тоже.
Большинство людей, кажется, не замечают, что тип контента неправильный, но время от времени появляются новые запросы поддержки с жалобами на эту проблему, поэтому мы хотели бы это исправить.
насколько сильно это может испортить ситуацию для наших существующих клиентов?
Они могли бы полностью потопить их линкоры, если бы они написали код, основанный на этом Тип содержимого быть неверным.
Я не ожидал, что библиотеки будут выдавать ошибки, но я ожидаю, что в некоторых случаях поведение строгих библиотек переопределяется для обработки неправильного типа MIME.
Если ваш API имеет значение версии / редакции где-то в поле запроса, увеличьте его, и в новой версии верните правильный тип, но продолжайте возвращать неправильный тип в более старых версиях. Если у вас нет такого поля запроса, сейчас хорошее время, чтобы добавить его.
Ожидаете ли вы, что многие разные клиентские библиотеки HTTP будут выдавать фатальные ошибки, увидев такое изменение?
Нет. Каждая клиентская библиотека HTTP, с которой я знаком, будет игнорировать заголовок типа содержимого, если программист специально не прочитает этот заголовок и не сделает с ним что-нибудь. Я могу представить себе библиотеку, в которой content-type: application / json автоматически вызывает включение парсера json, но я не знаю ни одного случая, когда это действительно происходит.
Большинство людей, кажется, не замечают, что тип контента неправильный, но время от времени появляются новые запросы в службу поддержки с жалобами на эту проблему, поэтому мы хотели бы ее исправить.
Как они заметили неправильный заголовок? Возможно, на это стоит посмотреть, потому что, если неправильный заголовок действительно вызывал у них проблемы, они явно не просто игнорировали его, и у них могут возникнуть проблемы, если он будет исправлен.
Слишком сложно сказать, не получив одобрения всех ваших клиентов. Я бы предложил использовать один из следующих двух подходов для обновления вашего API до версии v.Next.
В любом случае сообщите своим клиентам об изменениях, которые вы хотите внести, и о целевой дате / времени переключения. Поощряйте их проводить тестирование задолго до установленной даты, чтобы гарантировать отсутствие сбоев в обслуживании.
Убедитесь, что у вас есть специальная страница с подробным описанием изменений, внесенных в v.Next. Это должно быть включено в сообщения, отправляемые вашим клиентам. Если вы обсуждали какие-либо исправления с существующими клиентами, укажите их на этой странице.
Наконец, найдите грань между чрезмерным общением с клиентами и рассылкой им спама. Эти уведомления можно легко пропустить, поскольку появляются более срочные / срочные приоритеты.
FWIW, если что-то в настоящее время работает, я бы особо не беспокоился об этом. Если, например, вы обнаружите, что это вызывает серьезную уязвимость в системе безопасности, это может стать отличной причиной для внесения этого изменения. В противном случае я бы дождался чего-то более важного, чтобы включить это изменение.
Вот пример библиотеки (ну, отдельной команды), которая может сломаться:
В Powershell командлет Invoke-RestMethod иначе действует с JSON. Если результатом запроса является JSON, XML или ATOM / RSS (и я думаю, что он основан на заголовке), он анализирует / десериализует его и возвращает собственные объекты, в противном случае он возвращает необработанные данные.
Таким образом, существующий код будет написан для работы со строкой (возможно, передав ее в ConvertFrom-Json), и внезапно начинал давать сбои.
Я заметил два последствия: