GET https://api.partnercenter.microsoft.com/v1/customers/<customer-tenant-id>
Тип сервиса вынесен в суб-домен. Версия — как часть адреса — v1. Далее просто без введения всяких разделов — сразу запрос к сущности customers. И там все в подобном роде. К примеру, запрос девайсов:
GET https://api.partnercenter.microsoft.com/v1/customers/47021739-3426-40bf-9601-61b4b6d7c793/deviceBatches
Без разделения на секции в адресе, хотя по смыслу в документации разделение они выполнили.
А вот Гугле и Амазон — поступают иначе — вводят секцию, к примеру:
POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/orders/{orderId}/cancel
и
GET /messaging/v1/orders/{amazonOrderId}
Общее — везде есть версия. А вот раздел — MS как бы принципиально отказалась бить на разделы. Это просто так совпало или они придерживаются каких-то принципов?
Так же в какой иерархии лучше — сначала секция потом версия или наоборот?
Здравствуйте, Shmj, Вы писали:
S>Общее — везде есть версия. А вот раздел — MS как бы принципиально отказалась бить на разделы. Это просто так совпало или они придерживаются каких-то принципов?
Здравствуйте, Ночной Смотрящий, Вы писали:
S>>Общее — везде есть версия. А вот раздел — MS как бы принципиально отказалась бить на разделы. Это просто так совпало или они придерживаются каких-то принципов?
НС>https://highload.today/api-gateway-endpoints/
Так REST — это же не стандарт, а набор пожеланий (обычно вредных) по организации API, так что логично, что все делают по разному.
А конкретика — зависит от контекста и задач.
Если у тебя нет в схеме AGW — разумно вытащить публичный API в отдельный сегмент пути, так как это упростит написание регексов для ингресса. К примеру, если у сервиса есть внешний публичный API и внутрикластерный, который доступен только внутри DMZ, то удобно сделать первый, к примеру, с префиксом /api, а второй с префиксом /internal-api.
А вот если у тебя в схеме есть AGW, то тебе все равно собирать публичный API на специально выделенном сервисе, и там можно все собрать прям в корне, в максимально простом и красивом виде.
Здравствуйте, Shmj, Вы писали:
S>Так же в какой иерархии лучше — сначала секция потом версия или наоборот?
Секцию URI выносят перед версией только в одном случае: когда есть понятие подсистем. Это означает, что за конкретной функцильностью стоит некий относительно изолированный сервис, который занимается этой работой. Поэтому у него возникает своё пространство имён (секция), функциональность и естественно версионность всего этого. Это так же означает, что вы имеете дело с микросервисной архитектурой, по крайней мере с точки зрения дизайна этой архитектуры. Физически все эти "микросервисы" могут работать в одном процессе и быть частью одного приложения с точки зрения ОС.
Почему так делают? Для того чтобы облегчить ведение проекта. Если же делать очень большой сервис с глобальной версионностью, то при каждом "ломающем" изменении даже части API вам придется поднимать версию и для всего остального API, что может быть некрасиво и накладно с точки зрения документирования и использования. А вот если отдельно выделить, например, сервис аутентификации и сервис бизнес-логики и каждый поместить в свою "секцию" URI со своей версионностью, то вести их становится намного легче, так как сложность всей системы переводится из плоскости m * n в плоскость m + n (m = кол-во методов сервиса аутентификации, n = кол-во методов сервиса бизнес логики). А представьте теперь, что у вас добавляются и другие хотелки. Поэтому со временем такой подход начинает приносить очень ощутимые плоды. Я бы сказал, что это единственный правильный подход при проектировании стабильного API для внешнего использования, да и для внутреннего тоже.