Версионирование RESTful сервисов?

Question

У меня развернута веб-служба RESTful на http://example.com/v1/SomeResource. Однажды новая версия протокола (, не совместимая с предыдущими версиями ) развернута на http://example.com/v2/SomeResource. С клиента это обновление может произойти в любое время между двумя HTTP-запросами.

Как сервер указывает клиенту, что он больше не поддерживает вызовы v1, и ожидается, что клиент обновится до v2? Можно ли использовать соответствующий код ответа?

Я бы хотел предоставить клиенту следующую информацию:

1. Произошло несовместимое обновление. Клиент не может использовать новую службу, поскольку протокол может быть совершенно другим.
2. URL-адрес нового клиентского программного обеспечения.
3. Сообщение, объясняющее пользователям, что они должны обновить.

Answer 1

Я рекомендую следующую статью Питера Уильямса

• Управление версиями REST Web Services

Answer 2

Лучшая практика:

Вероятно, лучше не указывать версии в URL и сделать новые ресурсы обратно совместимыми со старыми.

Обратная совместимость:

Если вам нужно сохранить v1 в URL-адресе и создавать v2-URL-адреса, вам нужно решить, хотите ли вы поддерживать оба формата или сделать старый v1 устаревшим. Если вы решите сделать старый v1 устаревшим, я бы порекомендовал вернуть 303 или 401 для любого, кто запрашивает URL v1.

Устаревшие старые URL-адреса:

Я бы рекомендовал использовать 303 См. Другое. Или, если нет соответствующего перенаправления, используйте 410 Gone.

Источник

303 См. Другое

Ответ на запрос может быть найдено под другим URI и ДОЛЖНО быть получены с помощью метода GET на этот ресурс. Этот метод существует в первую очередь, чтобы позволить вывод POST-активированный скрипт для перенаправления пользовательский агент для выбранного ресурса. новый URI не является заменой ссылки для первоначально запрошенного ресурса. Ответ 303 НЕ ДОЛЖЕН кэшироваться, но ответ на второй (перенаправленный) запрос может быть кэшируется.

Другой URI ДОЛЖЕН быть задан поле Расположение в ответе. Если метод запроса не был HEAD, субъект ответа ДОЛЖЕН содержать краткую гипертекстовую заметку с гиперссылка на новый URI.

Примечание: многие пользовательские агенты до HTTP / 1.1 не понимают 303 статус. Когда совместимость с такими клиентами является проблемой, Вместо этого можно использовать код состояния 302, так как большинство пользовательских агентов реагируют на ответ 302, как описано здесь для 303.

Документирование всего:

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

Answer 3

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

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

Из статьи RESTful Web-сервисы: основы .

Answer 4

Я бы рекомендовал вместо этого использовать 301 (301 перемещено навсегда). Читайте почему .

Надеюсь, это поможет, Bruno Figueiredo