Соглашения об именах ресурсов REST API - Пользователь или Пользователи (множественное число) - PullRequest
Новая
       20

Соглашения об именах ресурсов REST API - Пользователь или Пользователи (множественное число)

0 голосов
/ 06 января 2019

Длинная версия

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

Хотя это, конечно, зависит от личных предпочтений; Есть определенные вещи, которые поощряются сообществом. Например, большинство людей, включая меня, будут называть имена своих ресурсов множественными: 

GET /notifications
POST /posts

Однако бывают случаи, когда плюрализм просто кажется неправильным. Рассмотрим следующий пример, где user по существу представляет зарегистрированного пользователя, а не весь ресурс users:

Конечные точки, относящиеся только к аутентифицированному пользователю 

// Phone Verification
POST /user/phone/request
POST /user/phone/resend
POST /user/phone/verify

// User creation based on authenticated and verified phone
POST /user

// Update authenticated user's profile
PUT /user

// Delete the authenticated user
DELETE /user

// Add/remove the authenticated user's profile image
POST /user/image
DELETE /user/image

// Update the authenticated user's device token
PUT /device/token

Конечные точки, которые получают доступ ко всему ресурсу пользователя 

GET /user
GET /user/{id|self}

В приведенном выше примере, мне кажется , как единственное user имя ресурса больше подходит для данных на большинстве конечных точек, user относится к аутентифицированному user, а не вся база данных users. Но, с другой стороны, GET /user возвращает всех пользователей просто неправильно ...

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

Короткая версия

TLDR - Проще говоря, рассмотрим следующие две конечные точки: 

// Get all users
GET /users

// Update the authenticated user's device token
PUT /user/device

Оба вышеперечисленных кажутся мне правильными. Проблема с вышесказанным заключается в том, что я не смогу получить и user, и users, по моему мнению, это должен быть один или другой.

Дилемма; Зачем мне использовать user, когда ресурс относится ко всей базе данных пользователей? Зачем мне использовать users, если ресурс относится только к аутентифицированному пользователю?

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

Обновление

После некоторых глубоких размышлений я нашел альтернативное решение, но я все еще не уверен в этом на 100%, поскольку не слишком заинтересован в использовании имени ресурса auth.

Учтите это: 

// auth = authenticated user
// users = users collection

POST /auth/request
POST /auth/resend
POST /auth/verify

POST /auth
PUT /auth
DELETE /auth

POST /auth/image
DELETE /auth/image

PUT /auth/device/token

GET /users
GET /users/{id}

Ответы [ 2 ]

0 голосов
/ 11 января 2019

Если ваш API поддерживает просмотр данных устройств других пользователей, API может выглядеть следующим образом: / users / $ user_id / devices

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

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

0 голосов
/ 06 января 2019

Очевидно, что существуют разные мнения по этому вопросу, ответ ниже содержит мои личные взгляды. Суть в том, что все это довольно субъективно и зависит от того, как вы смотрите на определенный (тип) ресурса.

Зачем мне использовать user, когда ресурс относится ко всем пользователям база данных?

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

Зачем мне использовать users, когда ресурс относится только к аутентифицированный пользователь?

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

// Update the authenticated user's device token
PUT /user/device

Вы можете интерпретировать «обновление токена устройства аутентифицированного пользователя» следующим образом:
Добавьте токен устройства в объект user из коллекции ресурсов users.

...