Принуждение потребителей веб-API принимать новые поля в ответах

Question

Я создаю v2 существующего веб-API RESTful.

Ответы - это списки объектов в формате JSON, примерно в виде:

[
  {
     name1=value1,
     name2=value2,
  },
  {
     name1=value3,
     name2=value4,
  }
]

Одна проблема, с которой мы столкнулисьv1 заключается в том, что некоторые клиенты получают доступ к полям по целочисленной позиции, а не по имени.Это означает, что если мы решим добавить поля к ответу (который мы изначально рассматривали как изменение, сохраняющее совместимость), то часть кода нашего клиента нарушится, если мы не добавим поля в конце.Даже в этом случае код других клиентов в любом случае нарушается, потому что они каким-то образом потерпят неудачу при обнаружении неожиданного имени атрибута.

Чтобы противостоять этому в v2, мы рассматриваем случайное изменение порядка полей в каждом ответе.Это заставит клиентов индексировать поля по имени, а не по позиции.

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

Хотя это звучит несколько странно, у него есть преимущество в том, что мы сможем добавлять новые поля, будучи уверенными, что это не нарушаетлюбые клиенты.Это означает, что мы можем выпускать совместимые обновления для v2.1, v2.3 и т. Д. По одному и тому же URL, и это означает, что нам нужно будет поддерживать и поддерживать только меньшее количество версий API.

Альтернативой являетсявыпускать несовместимые версии v3, v4 по новым URL-адресам, что означает, что нам придется поддерживать и поддерживать множество несовместимых версий API, что сделает нас немного тоньше.

Это плохая идея, и еслитак зачем?Есть ли другие подобные идеи, о которых мне следует подумать?

Обновление: Первая пара ответов указывает на то, что если я задокументирую проблему (т.е. укажите в документах, что поля могут быть добавлены)или переупорядочить), то я больше не виноват, если клиентский код ломается, когда я впоследствии добавляю или переупорядочиваю поля.К сожалению, я не думаю, что это подходящий вариант для нас: многие десятки организаций полагаются на функциональность наших API для реальных транзакций с существенными финансовыми последствиями.Эти организации не являются технически ориентированными - и полученные реализации на стороне клиента охватывают весь спектр технических знаний.Мы уже сделали документ, подтверждающий, что поля могут быть добавлены или переупорядочены в документах для v1, и это явно не сработало, потому что теперь нам приходится выпускать v2, потому что многие клиенты из-за нехватки времени илиопыт или способность, все еще писал код, который ломается, когда мы добавляем новые поля.Если бы я сейчас добавил поля к интерфейсу, это сломало бы нам дюжину различных интерфейсов компании, что означает, что они (и мы) теряют деньги каждую минуту.Если бы я отказался отменить изменение или исправить его, сказав «Они должны были прочитать документы!», То я скоро уйду с работы, и это правильно.Мы можем попытаться обучить «провалившихся» партнеров, но это обречено на провал, так как проблема с каждым месяцем увеличивается, по мере того, как мы продолжаем расти.Мой вопрос заключается в том, могу ли я системно устранить всю проблему на проходе, не допуская возникновения этой ситуации, независимо от того, что пытаются сделать клиенты?Если методы, которые я предлагаю, будут работать, почему я не должен их использовать?Почему никто не использует их?

Answer 1

Я решил бежать с описанными техниками, по максимуму.Я не слышал никаких возражений против них, которые держат для меня водуОтвет Брайана о повторном использовании одного и того же URI для разных версий API - это солидная и высоко ценимая дополнительная идея (с upvote), но я не могу наградить ее «лучшим ответом», потому что он не доходит до сутимой оригинальный вопрос.

Answer 2

Если вы хотите, чтобы ваши типы носителей были «эволюционирующими», четко изложите это в документации.Точно так же, если порядок размещения полей не гарантирован, проясните это явно.Если вы предоставляете пример кода для своего API, убедитесь, что он не зависит от порядка полей.

Однако, даже если предположить, что вам нужно поддерживать разные версии ваших типов носителей, вам не нужно указывать версию URI .REST дает вам возможность поддерживать тот же независимый от версии URI, но использовать согласование содержимого HTTP (через заголовки Accept и Content-Type), чтобы предлагать разные полезные нагрузки на одном и том же URI.

Поэтому любой клиент, который явно не желает принимать вашу новую кодировку v2 / v3 / etc, не получит ее.По умолчанию вы можете вернуть старую кодировку v1 с исходным порядком полей, и все эти хрупкие клиентские приложения будут работать нормально.Тем не менее, новые разработчики клиентов будут знать (благодаря вашей документации), чтобы через Accept указать, что они хотят и могут видеть новые поля, и им нет дела до их заказа.Лучше всего, вы можете (и должны) использовать один и тот же URI везде.Помните - разные полезные нагрузки, подобные этой, являются просто разными представлениями одного и того же базового ресурса, поэтому URI должен быть одинаковым.