ДИЗАЙН REST API - Получение ресурса через REST с разными параметрами, но с тем же шаблоном URL

У меня вопрос, связанный с дизайном URL-адресов REST. Я нашел несколько соответствующих сообщений здесь: разные представления RESTful одного и того же ресурса и здесь: URL-адрес RESTful для получения ресурса по разным полям но ответы не совсем ясны в отношении того, какие передовые практики и почему. Вот пример.

У меня есть URL-адреса REST для представления ресурса "пользователей". Я могу ПОЛУЧИТЬ пользователя с идентификатором или адресом электронной почты, но представление URL остается одинаковым для обоих. Просматривая множество блогов и книг, я вижу, что люди делали это разными способами. Например

прочтите эту практику в книге и где-нибудь в stackoverflow (я не могу снова найти ссылку)

GET /users/id={id}
GET /users/email={email}

прочтите эту практику во многих блогах

GET /users/{id}
GET /users/email/{email}

Параметры запроса обычно используются для фильтрации результатов ресурсов, представленных URL-адресом, но я видел и эту практику.

GET /users?id={id}
GET /users?email={email}

У меня вопрос: какая из всех этих практик будет наиболее разумной для разработчиков, использующих API, и почему? Я считаю, что в отношении дизайна URL-адресов REST и соглашений об именах нет установленных правил, но я просто хотел знать, какой путь мне следует выбрать, чтобы помочь разработчикам лучше понять API.

Любая помощь приветствуется!

По моему опыту, GET /users/{id} GET /users/email/{email}это наиболее распространенный подход. Я также ожидаю, что методы вернут 404 Not Found, если пользователь не существует с предоставленным idили email. Я не удивлюсь, увидевGET /users/id/{id} (хотя, на мой взгляд, это избыточно).

Комментарии к другим подходам

1. GET /users/id={id} GET /users/email={email}
   • Я не думаю, что видел это, и если бы я видел это, это было бы очень запутанным. Это похоже на попытку имитировать параметры запроса с параметрами пути.
2. GET /users?id={id} GET /users?email={email}
   • Думаю, вы попали в точку, когда упомянули об использовании параметров запроса для фильтрации.
   • Будет ли когда - нибудь смысл назвать этот ресурс с оба апом idи email(например GET /users?id={id}&email={email})? В противном случае я бы не стал использовать такой метод одного ресурса.
   • Я ожидал, что этот метод для получения списка пользователей с необязательными параметрами запроса для фильтрации, но я не ожидал id, emailчто среди параметров будет какой-либо уникальный идентификатор. Например: GET /users?status=BANNEDможет вернуть список заблокированных пользователей.

_{Посмотрите этот ответ на связанный вопрос.}

Если посмотреть на это прагматично, у вас есть группа пользователей:

/users   # this returns many

У каждого пользователя есть выделенное местоположение ресурса:

/users/{id}    # this returns one

У вас также есть несколько способов поиска пользователей:

/users?email={email}
/users?name=*bob*

Поскольку это все параметры запроса к / users, все они должны возвращать списки .. даже если это список из 1.

Я написал здесь сообщение в блоге о прагматичном дизайне RESTful API, в котором говорится об этом, среди прочего, здесь: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

О пользовательских ресурсах

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

на пути /users/[user_id]вы можете ожидать, что произойдет несколько вещей:

1. вы должны получить одноэлементный ресурс, представляющий пользовательский ресурс с его идентификатором [user_id] или
2. не найдено 404ответ если пользователя с идентификатором [user_id] не существует, или
3. запрещенный 401, если вам не разрешен доступ к запрошенному пользовательскому ресурсу.

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

Вы можете запросить путь /usersс параметрами запроса ( GETParameters). Это вернет коллекцию с пользователями, которые соответствуют запрошенным критериям. Возвращаемая коллекция должна содержать пользовательские ресурсы с указанием пути к ресурсам в ответе.

Параметры могут быть любым полем, присутствующим в ресурсах коллекции; firstName, lastName,id

Об электронной почте

Электронная почта может быть ресурсом или свойством / полем ресурса пользователя.

- Электронная почта как собственность пользователя:

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

{ 
  id: 1,
  firstName: 'John'
  lastName: 'Doe'
  email: 'john.doe@example.com'
  ...
}

Это означает , что не существует никаких специальных конечных точек для электронной почты, но теперь вы можете найти пользователя по его электронной почте, отправив следующий запрос: /users?email=john.doe@example.com. Что (при условии, что электронные письма уникальны для пользователей) вернет коллекцию с одним пользовательским элементом, который соответствует электронной почте.

- Электронная почта как ресурс:

Но если электронные письма от пользователей также являются ресурсами. Затем вы можете создать API, который /users/[user_id]/emailsвозвращает набор адресов электронной почты для пользователя с идентификатором user_id. /users/[user_id]/emails/[email_id]возвращает адрес электронной почты пользователя с user_id и ['email_id']. Что вы используете в качестве идентификатора, зависит от вас, но я бы предпочел целое число. Вы можете удалить электронное письмо от пользователя, отправив DELETEзапрос по пути, который идентифицирует электронное письмо, которое вы хотите удалить. Так, например, DELETEon /users/[user_id]/emails/[email_id]удалит электронное письмо с email_id, которое принадлежит пользователю с user_id. Скорее всего, только этому пользователю разрешено выполнять эту операцию удаления. Остальные пользователи получат ответ 401.

Если у пользователя может быть только один адрес электронной почты, вы можете придерживаться его. /users/[user_id]/email Это возвращает одноэлементный ресурс. Пользователь может обновить свой адрес электронной почты, PUTуказав адрес электронной почты на этом URL.