REST API - как правильно отправить ID по запросу http?

Question

Допустим, у меня есть конечная точка URI:

:GET /v1/permissions

, которая выбирает все разрешения для версии 1.

Можно также запросить это:

:GET /permissions

Который будет запрашивать все разрешения для последней версии по умолчанию.

Теперь я хочу выбрать все разрешения для конкретного пользователя.

Я хочу знать, что такоеправильный и респектабельный способ отправки идентификатора пользователя - в конечной точке URI ИЛИ в заголовках HTTP-запроса ИЛИ в качестве параметра GET.

Например:

Метод 1:

:GET /v1/groups/:id/permissions

Метод 1.1:

:GET /v1/:id/permissions

Метод 2:

:GET /v1/permissions,
"If-Match": "[REPLACE_ID_HERE]" (header)

Метод 3:

:GET /v1/permissions/?groups=REPLACE_ID_HERE

Все они будут работать.

Но какой правильный путь?

Answer 1

Наиболее распространенным способом разработки REST API является отслеживание структуры ресурсов (и / или подресурсов).то есть api url будет начинаться с вашего имени ресурса, за которым следует уникальный идентификатор для ресурса в случае одного ресурса GET, PUT (обновление) или DELETE.

Пример: 1. / users / $ unique_user_id - HTTP GET - извлекает сведения об одном пользователе.

/ users / $ unique_user_id - HTTP PUT - обновляет данные пользователя, идентифицированные идентификатором, с соответствующими данными.

/ users / $ unique_user_id - HTTP DELETE - Удаляет пользователя, идентифицированного идентификатором.

Если ваш случай обрабатывает скважинаУстановленная связь между двумя ресурсами, вы можете обрабатывать их как подресурсы родителя.Пример: / users / $ user_id / permissions / groups / $ group_id / permissions

Эта модель подойдет, если у вас не будет требования извлекать разрешения для нескольких ресурсов (вид фильтрации) Пример: / permissions? Group_ids = 1,2,3 / permissions? User_ids = 4,5,6

Answer 2

В соответствии со спецификацией REST вам сначала необходимо определить, какой базовый ресурс вы запрашиваете.Имя ресурса идет первым в URI.В вашем случае это разрешение.Следовательно, URI будет начинаться с разрешения, с необязательного префикса версии (поскольку весь API является версионным)

После имени ресурса необходимо указать либо конкретный ресурс, либо параметры запроса, чтобы получить широкий список.Теперь у вас есть два варианта, в зависимости от того, что вы получаете.1) разрешение для человека: в этом случае вам нужно ввести параметр запроса, так как сам API не сможет угадать, для чего нужен идентификатор.Следовательно, это будут permissions /? PersonId = 123 2) подробности разрешения конкретного разрешения: Используется, когда у вас есть предварительно выбранный список разрешений, возможно, в результате вышеупомянутого API.В этом случае идентификатор будет принадлежать самому ресурсу, поэтому он будет указан в качестве идентификатора ресурса как permissions / 5e55, где 5e55 - первичный ключ указанного разрешения, сведения о котором запрашиваются.

Основная сложность в такой конструкции заключается в правильной идентификации первичного идентификатора ресурса и вторичного идентификатора ... Первичный идентификатор помещается непосредственно в тип 2, а вторичный указывается в качестве параметра запроса.

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

Answer 3

Два предварительных пункта:

• Официальной спецификации REST, выпущенной центральным органом, не существует.Вся парадигма происходит от довольно тонкой (но гениальной) технической схемы, написанной Роем Филдингом в 2000 году.
• Однако есть несколько хороших книг по этому вопросу и сотни тысяч реализаций, которые привели к фирменный отраслевой стандарт .

Один из этих стандартов состоит в том, что URL-адреса REST относятся к ресурсам и идентификаторам, встроенным в эти URL-адреса, ссылки на ресурсы того же типа.Таким образом, GET /groups/:groupdId является ортодоксальным (стандартная реализация, которая соответствует ожиданиям большинства программистов), тогда как GET /groups/:permissionId - нет.

Возвращаясь к четырем рассматриваемым альтернативам:

Метод 1:

:GET /v1/groups/:id/permissions

Является ортодоксальным, поскольку ресурс, управляемый конечной точкой, имеет тип Group и: id является идентификатором группы.

Метод 1.1:

:GET /v1/:id/permissions

Неортодоксален, так как нет указаний на то, к какому типу ресурсов относится URL.

Метод 2:

:GET /v1/permissions,
"If-Match": "[REPLACE_ID_HERE]" (header)

Неортодоксально, поскольку ожидается, что идентификаторы ресурсов будут передаваться как часть URL.

Метод 3:

:GET /v1/permissions/?groups=REPLACE_ID_HERE

Isортодоксальный, поскольку здесь ресурс равен Permission, а groupId применяется в качестве фильтра, для которого параметры запроса являются адекватным средством.

Answer 4

Но какой правильный путь?

Это распространенное заблуждение .

Архитектурный стиль REST не предусматривает какой-либо дизайн URI ^{(см. Примечания ниже)} .Это полностью зависит от вас, чтобы выбрать URI, которые лучше идентифицируют ваши ресурсы .

---

Синтаксис URI определен в RFC 3986 .Как правило, путь организован в иерархической форме (с сегментами, разделенными /) и может содержать неиерархические данные в компоненте запроса (начиная с ?).

Эти подходы кажутся подходящими для определения разрешений конкретной группы :

• /v1/groups/:id/permissions

• /v1/permissions?groups=id

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

---

^{Примечание 1: Архитектурный стиль REST описан в глава 5 диссертации Роя Т. Филдинга, и в ней определяется набор ограничений, которым должны следовать приложения, которые следуют такой архитектуре.Однако в нем ничего не сказано о том, какими должны быть URI.}

^{Примечание 2: Примеры популярной статьи написано Мартином Фаулером, объясняющим модель, определенную Леонардом Ричардсоном предлагает структуру URI, которая выглядит дружественной и легкой для чтения.}