REST API дизайн - обработка зависимостей между полей

Question

У меня есть ресурс под названием User, который имеет следующие поля: id, last_name, date_of_birth, organization_id и employee_number.

Я хочу определить конечную точку поиска, которая позволяет людям получать пользователей, удовлетворяющих некоторым условиям. Напр. люди, чьи last_name - «Джон», и которые рождаются после определенной даты. Для этого у меня может быть общая конечная точка /user/search, которая принимает эти условия как параметры GET.

Однако для некоторых запросов существуют определенные бизнес-правила. Напр. employee_number не могут быть запрошены, если они не сопровождаются полем organization_id. Я считаю, что это в документации уродливо. Как я должен применять это более элегантно?

Идея, которую я имею, состоит в том, чтобы иметь конечную точку /user/employee_number/:number, которая принимает organization_id как обязательный параметр GET. Но это не похоже на «ОТДЫХ». Любые другие предложения?

Answer 1

Во-первых, обратите внимание, что URI не определяют «RESTfulness». Это произвольные идентификаторы. Сказав это, мы обычно хотим иметь хорошие URI.

Ниже приведен неисчерпывающий список возможных вариантов.

Вариант 1. Hiearchical. Один из вариантов: если каждый работник зависит на орге то вы могли бы

/organization/:org/employee/:number 

Clean достаточно, но сотрудники/пользователями являются важными ресурсами, поэтому вы не можете их существующими в качестве ресурсов второго уровня. Справедливо.

Более серьезное возражение состоит в том, что это связывает пользователя с конкретной организацией. В реальной жизни люди передвигаются от org до org, и мы обычно не думаем об этом, влекущем за собой изменение личности. Фактически, при таком подходе ресурс - это пользовательский занятие в рамках данной организации, в отличие от того, чтобы быть самим пользователем.

Вариант 2. Матричные параметры. Если вы хотите/сотрудник/или пользователя, чтобы быть на высшем уровне, то другой вариант, так называемый matrix params:

/user;org=:org;number=:number 

Они не являются официальными, но так как Тим Бернерс-Ли придумал идею, люди рассматривать его как полуофициальное заявление. (Я думаю, что они выглядят уродливыми, но это чисто эстетическое суждение, это не имеет никакого отношения к RESTfulness.)

У этой проблемы возникает проблема с вариантом № 1 относительно перемещения сотрудников.

Вариант 3. Идентификатор базы данных. Третий вариант:

/user/:id 

где :id только некоторые идентификатор базы данных. Документируйте поиск как требующий орг + номер сотрудника, чтобы гарантировать уникальность. Это не должно быть «уродливым», например, у HAL spec есть хорошая схема документации, основанная на CURIE.

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

Приятный и чистый, но клиенты не могут напрямую строить URI, что, впрочем, соответствует философии HATEOAS/hypermedia, лежащей в основе REST: небольшое количество точек входа в API, а клиент перемещается (т.е. влияет на состояние приложения переходы), используя ссылки, встроенные в ресурсы.

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