Шаблон проектирования URI API REST: неиерархический путь?

Question

На работе мы обсуждаем, как структурировать наши будущие API.На данный момент мы собираемся запустить API, содержащий различные конечные точки пользовательской информации, и хотя мы опубликуем его под URI, например: api.mycompany.com/userinfo.Примеры конечных точек:

• api.mycompany.com / userinfo / users
• api.mycompany.com / userinfo / users / {id}
• api.mycompany.com / userinfo / api-docs <- документ Swagger для этого конкретного API будет находиться здесь </li>

Этот тип настройки позволил бы нам иметь server1.mycompany.com для размещения API и использоватьнаш балансировщик нагрузки / прокси для перенаправления трафика на api.mycompany.com/userinfo на server1.mycompany.com.Для нашего следующего API, работающего на server2.mycompany.com, у нас будет просто трафик пересылки балансировки нагрузки / прокси-сервера с api.company.com/transproduction на server2.mycompany.com, например:

• api.mycompany.com / транспорт / автомобили
• api.mycompany.com / транспорт / автомобили / {id}
• api.mycompany.com / транспорт / api-docs <- Swaggerдокумент для этого конкретного API будет находиться здесь </li>

Используя «userinfo» и «transport» в URI, у нас будет простой способ ссылаться на наши различные API в целом и простойспособ опубликовать Swagger UI вместе с фактическим API.

Моя проблема с этими URI заключается в том, что они не иерархические, а скорее как способ группировки конечных точек вместе.«Информация пользователя» также не является ресурсом, поэтому по сравнению с примерами API REST, которые обычно встречаются в сети, использование таких элементов, как «информация пользователя» и «транспорт» в пути, может не соответствовать рекомендациям.

этот дизайн нарушает какие-либо шаблоны проектирования REST API?Если да, то как бы вы предложили нам публиковать наши различные API-интерфейсы под одним fqdn (api.mycompany.com)?Или есть причины не использовать один fqdn для всех наших API?

Любой вклад будет принята с благодарностью.

Answer 1

REST не заботится о том, какое правописание вы используете для своего URI

Меня беспокоит то, что эти URI не иерархические, а скорее как способ группировки конечных точек вместе.«Userinfo» также не является ресурсом

Идентификаторы , являющиеся «иерархическими», (не обязательно) ничего не обещают относительно иерархии ресурсов .Тот факт, что существует ресурс, обозначенный /userinfo/users, не означает, что существует также ресурс, обозначенный /userinfo.Представьте себе хранилище ключей / значений, а не файловую систему.

Разработчик Rails может распознавать /userinfo и /transportation как пространства имен .

Если да, то какНе могли бы вы предложить нам публиковать наши разные API под одним fqdn (api.mycompany.com)?Или есть причины не использовать один fqdn для всех наших API?

В интервью 2014 Филдинг предложил этот ответ о версии:

По какой-то неожиданной причине всегда можно прийти, требуясовершенно другой API, особенно когда семантика изменения интерфейса или проблемы безопасности требуют отказа от ранее развернутого программного обеспечения.Моя точка зрения заключалась в том, что нет необходимости предвидеть такие потрясающие изменения с помощью идентификатора версии.У нас есть имя хоста для этого.То, что вы создаете, - это не новая версия API, а новая система с новым брендом.

Если вы щуритесь, это может означать, что другой API должен быть на разных (логических) хостах.

Answer 2

Не нарушает ли этот дизайн какие-либо шаблоны проектирования REST API?

Нет.Не существует «шаблонов проектирования REST API».И REST ничего не говорит о том, как должны выглядеть URL.REST говорит, что нужно обращаться с ними как с непрозрачными.Существует аргумент, что URL-адреса веб-API должны быть «взломанными», то есть легко понятными и изменяемыми человеком.Я бы сказал, что ваша структура URL взломана.Мне не известны какие-либо убедительные аргументы в пользу того, что URL-адреса должны иметь иерархическую природу.