RESTful API - дополнительные параметры и перегрузка по сравнению с несколькими маршрутами

Question

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

Для простого примера, скажем, некоторые клиенты хранят resourceId, а другие клиенты хранят resourceNumber.Кроме того, клиент может захотеть извлечь все ресурсы, где resourceCategory равно конкретному значению.

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

1. Имеется один маршрут, например GET /api/resource с параметрами для resourceId, resourceNumber и resourceCategory.На основании предоставленных параметров верните соответствующий ресурс (ы).

2. Имеет несколько маршрутов, таких как

   • GET /api/resource/id/{resourceId}
   • GET /api/resource/number/{resourceNumber}
   • GET /api/resource/category/{resourceCategory}.

Подход № 1 позволяет кому-то указать несколько вариантов, которые в некоторых случаях могут быть хорошими, но в других случаях это не так. (то есть resourceId и resourceNumber могут быть взаимоисключающими)

Я много гуглил и исследовал спецификацию OpenAPI (за которой я следую), ноне удалось найти ничего, что решает эту проблему.

Обратите внимание !!! Я не ищу отдельных мнений.Я хочу следовать любым существующим передовым методикам / стандартам, поэтому Я спрашиваю, существует ли передовой опыт или стандарт, такой как OpenAPI, который охватывает этот сценарий для веб-сервисов RESTful .

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

Answer 1

Я спрашиваю, существует ли передовая практика или стандарт, такой как OpenAPI, который охватывает этот сценарий для веб-служб RESTful.

REST не даст вам много рекомендаций.

Проблема заключается в следующем: выбор дизайна для ваших контроллеров является деталью реализации. Смысл REST в том, что эти детали реализации скрыты за единым интерфейсом.

Другими словами, ваш веб-сервис RESTful должен вести себя как веб-сайт или HTTP-кеш. Идентификаторы ресурсов - это просто ключи, используемые для поиска представлений в кэше.

/api/resource?resourceId={resourceId}
/api/resource?resourceNumber={resourceNumber}

Что касается REST, то это разные ресурсы. Нет особой причины предполагать, что они связаны друг с другом. Клиент не будет предполагать, что изменения одного обязательно означают изменения другого.

Семантически, идентификатор - это просто идентификатор, подобный суррогатному ключу в базе данных или UUID. Клиенты REST не пытаются извлечь значение из идентификатора.

REST-клиенты понимают правила для относительных ссылок , потому что они описаны в RFC 3986. Таким образом, вы можете выбирать различные варианты написания идентификаторов в зависимости от того, как обрабатываются точечные сегменты (сегменты пути и запрос обрабатывается по-разному).

С некоторыми написаниями URI легче работать, поскольку они соответствуют реализации URI шаблона , которая доступна вам. Шаблоны URI облегчают внедрение информации в идентификатор или извлечение ее позже; и шаблоны стандартизированы.

Но образцы все еще семантически независимы.

Двадцать лет назад нам нужно было беспокоиться о реализациях, которые не соответствовали стандартам, и поэтому вы могли выбирать написание идентификатора, чтобы избежать проблемных областей. Но опять же - это семантически не зависимая проблема.

Итак, все, что на самом деле осталось, - это набор соглашений о правописании для людей, и, как и имена переменных, аргументы в значительной степени связаны с политическими соображениями в местном контексте (т. Е. Ваше написание должно быть "согласованным" с тем, которое выбрал программист, сидящий на месте). за соседним столом.)