Там, кажется, нет стандарта.
Ответ 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 :
При сбое запроса API YouTube возвращает код ответа HTTP 4xx или 5xx, который в целом идентифицирует ошибку, а также ответ XML, который предоставляет более конкретную информацию об ошибках, которые привели к ошибке. Для каждой ошибки XML-ответ включает в себя элемент домена, элемент кода и, возможно, элемент местоположения.
Дальнейшее чтение: