У меня есть RESTful API. Есть 3 версии: v1, v2 и v3. Я собираюсь опубликовать v4, и мы решили прекратить v1, что означает, что все запросы http://example.com/v1/resourceне будут выполнены, но вызовы http://example.com/v2/resourceпродолжат работать.
Как правильно обозначить ошибку? Я рассмотрел использование 410 GONEкода состояния, но это означает, что ресурс больше не доступен. Вероятно, ресурс все еще доступен, но только он должен запрашиваться другим способом.
Я также рассмотрел общий 400код состояния, но это тоже казалось странным. Есть ли стандартный ответ на это?
Ответы:
Там, кажется, нет стандарта.
Ответ StackOverflow опирается на 410 GONE, но я думаю, что 301 MOVED PERMANENTLY более уместен.
Чтобы сделать правильный выбор, мы должны рассмотреть ваш конкретный случай. Если ваша цель состоит в том, чтобы все вызовы в API v1 не выполнялись без каких-либо дальнейших действий, 410 GONE работает для этого. Если вы хотите некоторой преемственности, такой как перенаправление клиента на более новую версию вашего API, где его вызов может быть успешным, 3XX работает, но какой вы выбираете? Я думаю, что если вы пытаетесь закрыть API v1, 301 MOVED PERMANENTLY помогает указать, что лучше, чем 303 SEE OTHER, потому что 301 предполагает, что все будущие запросы должны быть сделаны на новый URL, тогда как 303 не указывает, является ли эта ситуация постоянны.
Я бы порекомендовал спроектировать API таким образом, чтобы каждая версия оставалась обратно совместимой, чтобы 301 MOVED PERMANENTLY прозрачно поддерживал ваш API в актуальном состоянии, когда вы добавляете новые конечные точки для новых версий API. Я думаю, это то, что вы пытаетесь сделать в любом случае.
Коды состояния HTTP
Код состояния HTTP 302 изначально был слишком широким и, следовательно, стал неправильно реализованным / использованным, поэтому были созданы 303 и 307, чтобы различать вариант двойного использования 302. Некоторые API используют 303 для других целей.
301 MOVED PERMANENTLY - код состояния 301 (Moved Permanently) указывает, что целевому ресурсу был назначен новый постоянный URI, и любые будущие ссылки на этот ресурс должны использовать один из вложенных URI.
302 НАЙДЕН. - Код состояния 302 (Найдено) указывает, что целевой ресурс временно находится под другим URI. Поскольку перенаправление может иногда изменяться, клиент должен продолжать использовать эффективный URI запроса для будущих запросов.
303 SEE OTHER - ответ 303 на запрос GET указывает, что у исходного сервера нет представления целевого ресурса, который может быть передан сервером по HTTP. Однако значение поля Location относится к ресурсу, который является описательным для целевого ресурса, так что выполнение запроса поиска на этом другом ресурсе может привести к представлению, которое будет полезным для получателей, не подразумевая, что оно представляет исходный целевой ресурс.
410 GONE - код состояния 410 (Gone) указывает, что доступ к целевому ресурсу больше не доступен на исходном сервере и что это условие, вероятно, будет постоянным. Если исходный сервер не знает или не имеет возможности определить, является ли условие постоянным, вместо этого следует использовать код состояния 404 (не найден).
Как существующие API справляются с этим?
Может быть, вы можете взять страницу из Google API Google :
Дальнейшее чтение:
источник
Перенаправления отлично подходят для ресурсов, которые были перемещены. Вместо постоянного перенаправления 301 (которое указывало бы на переименование без изменений API), я бы использовал перенаправление 303 «Просмотреть другие».
источник
Нужно еще поддерживать наследие без перенаправлений? Даже если вы все еще поддерживаете его, и в глубине души он все еще реализован, 501 кажется довольно тесно связан с вашей ситуацией. Те, кто в курсе, все еще могут использовать его, в то время как случайные люди увидят 501 для v1.
http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
источник
Я бы использовал 503 с сообщением о том, что сервис недоступен, и указал бы использовать более новую версию. Это сообщение можно вернуть для 50% звонков и со временем постепенно увеличить до 100%.
Для прозрачной миграции я бы использовал 308 - постоянное перенаправление, так как этот метод не изменяет глагол (POST будет POST) в отличие от 301.
источник