Версия и секция в REST-API
От: Shmj Ниоткуда  
Дата: 20.09.22 17:19
Оценка: 5 (1)
Возьмем, для примера, API от Микрософта, которые все делают наиболее канонично: https://learn.microsoft.com/en-us/partner-center/develop/get-a-customer-by-id

Вот такой API -эндпоинт

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 как бы принципиально отказалась бить на разделы. Это просто так совпало или они придерживаются каких-то принципов?

Так же в какой иерархии лучше — сначала секция потом версия или наоборот?
Отредактировано 20.09.2022 17:29 Shmj . Предыдущая версия . Еще …
Отредактировано 20.09.2022 17:20 Shmj . Предыдущая версия .
Re: Версия и секция в REST-API
От: Ночной Смотрящий Россия  
Дата: 20.09.22 18:20
Оценка: 5 (1)
Здравствуйте, Shmj, Вы писали:

S>Общее — везде есть версия. А вот раздел — MS как бы принципиально отказалась бить на разделы. Это просто так совпало или они придерживаются каких-то принципов?


https://highload.today/api-gateway-endpoints/
... << RSDN@Home 1.3.17 alpha 5 rev. 62>>
Re[2]: Версия и секция в REST-API
От: Shmj Ниоткуда  
Дата: 20.09.22 20:10
Оценка:
Здравствуйте, Ночной Смотрящий, Вы писали:

S>>Общее — везде есть версия. А вот раздел — MS как бы принципиально отказалась бить на разделы. Это просто так совпало или они придерживаются каких-то принципов?


НС>https://highload.today/api-gateway-endpoints/


А где там ответ на вопрос?
Re: Версия и секция в REST-API
От: Дельгядо Филипп Россия  
Дата: 20.09.22 22:40
Оценка: 1 (1) +1 :)
Здравствуйте, Shmj, Вы писали:

Так REST — это же не стандарт, а набор пожеланий (обычно вредных) по организации API, так что логично, что все делают по разному.
А конкретика — зависит от контекста и задач.
Re[3]: Версия и секция в REST-API
От: Ночной Смотрящий Россия  
Дата: 21.09.22 07:05
Оценка: 5 (1)
Здравствуйте, Shmj, Вы писали:

НС>>https://highload.today/api-gateway-endpoints/

S>А где там ответ на вопрос?

Если у тебя нет в схеме AGW — разумно вытащить публичный API в отдельный сегмент пути, так как это упростит написание регексов для ингресса. К примеру, если у сервиса есть внешний публичный API и внутрикластерный, который доступен только внутри DMZ, то удобно сделать первый, к примеру, с префиксом /api, а второй с префиксом /internal-api.
А вот если у тебя в схеме есть AGW, то тебе все равно собирать публичный API на специально выделенном сервисе, и там можно все собрать прям в корне, в максимально простом и красивом виде.
... << RSDN@Home 1.3.17 alpha 5 rev. 62>>
Re: Версия и секция в REST-API
От: Aquilaware  
Дата: 04.12.22 12:00
Оценка:
Здравствуйте, Shmj, Вы писали:

S>Так же в какой иерархии лучше — сначала секция потом версия или наоборот?


Секцию URI выносят перед версией только в одном случае: когда есть понятие подсистем. Это означает, что за конкретной функцильностью стоит некий относительно изолированный сервис, который занимается этой работой. Поэтому у него возникает своё пространство имён (секция), функциональность и естественно версионность всего этого. Это так же означает, что вы имеете дело с микросервисной архитектурой, по крайней мере с точки зрения дизайна этой архитектуры. Физически все эти "микросервисы" могут работать в одном процессе и быть частью одного приложения с точки зрения ОС.

Почему так делают? Для того чтобы облегчить ведение проекта. Если же делать очень большой сервис с глобальной версионностью, то при каждом "ломающем" изменении даже части API вам придется поднимать версию и для всего остального API, что может быть некрасиво и накладно с точки зрения документирования и использования. А вот если отдельно выделить, например, сервис аутентификации и сервис бизнес-логики и каждый поместить в свою "секцию" URI со своей версионностью, то вести их становится намного легче, так как сложность всей системы переводится из плоскости m * n в плоскость m + n (m = кол-во методов сервиса аутентификации, n = кол-во методов сервиса бизнес логики). А представьте теперь, что у вас добавляются и другие хотелки. Поэтому со временем такой подход начинает приносить очень ощутимые плоды. Я бы сказал, что это единственный правильный подход при проектировании стабильного API для внешнего использования, да и для внутреннего тоже.
 
Подождите ...
Wait...
Пока на собственное сообщение не было ответов, его можно удалить.