Форматы версий для REST API - PullRequest
Новая
       17

Форматы версий для REST API

0 голосов
/ 19 октября 2018

Я пытаюсь использовать стратегии управления версиями для REST API, следующие Microsoft REST API Guidelines и пытаюсь использовать для моего решения ASP.NET Core.

Из руководства:

Поддерживаются две опции для указания версии запроса REST API:

Рекомендации по выбору между двумя вариантами следующие:

...

Сервисы, которые гарантируют стабильность URL-путей их REST API, даже в будущих версиях API, МОГУТ использовать механизм параметров строки запроса.Это означает, что наименование и структура отношений, описанных в API, не могут развиваться после того, как API поставляется, даже между версиями с критическими изменениями. Сервисы, которые не могут обеспечить стабильность пути URL-адреса в будущих версиях, ДОЛЖНЫ встраивать версию в URL-адреспуть.

Я думаю, что я не совсем понимаю, что означает «не может эволюционировать» означает в -

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

Не могли бы вы дать немного расширенное определение?

И есть ли у вас пример Сервисов, которые не могут обеспечить стабильность пути URL в будущих версиях ?

Спасибо:)

1 Ответ

0 голосов
/ 13 ноября 2018

В рекомендациях Microsoft не рекомендуется использовать параметры запроса для управления основными версиями, если вы ожидаете изменения имен ресурсов в самих URL.

При управлении версиями параметров пути вы можете иметь:

https://api.contoso.com/v1.0/products/users https://api.contoso.com/v2.0/items/customers

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

Как говорит @Archer, наиболее распространенная практика -использовать основную версию без точки или подрывной деятельности, а версии параметров запроса встречаются редко, за исключением параметров даты версии, таких как FourSquare (https://developer.foursquare.com/docs/api/configuration/versioning),, которые обычно используются в дополнение к основной версии пути и обычно управляют небольшими изменениями APIчем меняется имя ресурса.

...