Соглашение REST URI - имя ресурса в единственном или множественном числе при его создании - PullRequest
448 голосов
/ 27 июля 2011

Я новичок в REST и заметил, что в некоторых сервисах RESTful они используют разные URI ресурса для обновления / получения / удаления и создания.Например,

  • Создать - используя / resources с методом POST (наблюдайте во множественном числе) в некоторых местах, используя / resource (единственное число)
  • Обновление - использование / resource / 123 с методом PUT
  • Получение - Использование /resource / 123 с методом GET

Я немного запутался в этом соглашении об именовании URI.Что мы должны использовать множественное число или единственное число для создания ресурса?Какими должны быть критерии при принятии решения?

Ответы [ 20 ]

5 голосов
/ 18 августа 2015

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

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

3 голосов
/ 25 марта 2016

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

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

И в этом контексте языковые правила могут дать вам только следующее:

Каталог может содержать несколько файлов и / или подкаталогов, поэтому его имя должно быть во множественном числе.

И мне это нравится.
Хотя, с другой стороны, это ваш каталог, вы можете назвать его «a-resource-or-множественные ресурсы», если вы этого хотите. Это не очень важно.

Важно то, что если вы поместите файл с именем «123» в каталог с именем «resourceS» (в результате /resourceS/123), вы не сможете ожидать, что он будет доступен через /resource/123.

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

Примечание: Технически вы можете создавать "символические ссылки", чтобы к /resources/123 также можно было получить доступ через /resource/123, но первое еще должно существовать!

2 голосов
/ 12 апреля 2018

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

Как насчет обоих? И под этим я имею в виду использование единственного числа для всего вашего API, а затем создание маршрутов для пересылки запросов, сделанных во множественном числе, в единственную форму.Например:

GET  /resources     =     GET  /resource
GET  /resources/1   =     GET  /resource/1
POST /resources/1   =     POST /resource/1
...

Вы получаете изображение.Никто не ошибается, прилагая минимальные усилия, и клиент всегда сделает это правильно.

1 голос
/ 14 июня 2017

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

Если все ваши ресурсы находятся на верхнем уровне, то вы можете обойтись без единственного представления.Избегать перегиба - большая победа.

Если вы используете какие-либо глубокие ссылки для представления запросов по отношениям, тогда разработчикам, пишущим против вашего API, может помочь более строгое соглашение.

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

Предположим, у нас есть следующая модель.

interface User {
    <string>id;
    <Friend[]>friends;
    <Manager>user;
}

interface Friend {
    <string>id;
    <User>user;
    ...<<friendship specific props>>
}

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

GET /users/{id}/friends/{friendId}/manager

Вот еще несколько примеров:

  • GET /users - список пользовательских ресурсов в глобальной коллекции пользователей
  • POST /users - создание нового пользователя в глобальной коллекции пользователей
  • GET /users/{id} - получить конкретного пользователя из глобальной коллекции пользователей
  • GET /users/{id}/manager - получить менеджера определенного пользователя
  • GET /users/{id}/friends - получитьсписок друзей пользователя
  • GET /users/{id}/friends/{friendId} - получить конкретного друга пользователя
  • LINK /users/{id}/friends - добавить ассоциацию друзей к этому пользователю
  • UNLINK /users/{id}/friends -удалить ассоциацию друзей у этого пользователя

Обратите внимание, как каждый уровень отображается на родителя, на которого можно воздействовать.Использование разных родителей для одного и того же объекта нелогично.Извлечение ресурса на GET /resource/123 не оставляет никаких указаний на то, что создание нового ресурса должно быть сделано на POST /resources

1 голос
/ 10 августа 2016

Использование множественного числа для всех методов более практично, по крайней мере, в одном аспекте: если вы разрабатываете и тестируете ресурсный API с помощью Postman (или аналогичного инструмента), вам не нужно редактировать URI при переключении с GET на PUT на POST и т. д.

1 голос
/ 28 июня 2019

Идентификатор в маршруте должен рассматриваться так же, как индекс для списка, и присвоение имен должно выполняться соответствующим образом.

numbers = [1, 2, 3]

numbers            GET /numbers
numbers[1]         GET /numbers/1
numbers.push(4)    POST /numbers
numbers[1] = 23    UPDATE /numbers/1

Но некоторые ресурсы не используют идентификаторы в своих маршрутах, потому что есть только один, или пользователь никогда не имеет доступа к более чем одному, поэтому это не списки:

GET /dashboard
DELETE /session
POST /login
GET /users/{:id}/profile
UPDATE /users/{:id}/profile
0 голосов
/ 03 июля 2019

Оформление заказа Google Руководство по разработке API: имена ресурсов для другого подхода к именованию ресурсов.

Вкратце:

  • Коллекции названы множественным числом.
  • Отдельные ресурсы именуются со строкой.
|--------------------------+---------------+-------------------+---------------+--------------|
| API Service Name         | Collection ID | Resource ID       | Collection ID | Resource ID  |
|--------------------------+---------------+-------------------+---------------+--------------|
| //mail.googleapis.com    | /users        | /name@example.com | /settings     | /customFrom  |
| //storage.googleapis.com | /buckets      | /bucket-id        | /objects      | /object-id   |
|--------------------------+---------------+-------------------+---------------+--------------|
0 голосов
/ 27 февраля 2017

Для меня множественное число манипулирует коллекцией , тогда как единственные числа манипулируют элементом внутри этой коллекции.

Коллекция допускает методы GET / POST / DELETE

Элемент допускает методы GET / PUT / DELETE

Например

POSTна / ученики добавят нового ученика в школу.

УДАЛИТЬ на / ученики удаляют всех учеников в школе.

УДАЛИТЬ на / ученик / 123 удалит ученика 123 из школы.

Это может показаться незначительным, но некоторые инженеры иногда забывают идентификатор.Если маршрут всегда был множественным и выполнял УДАЛЕНИЕ, вы можете случайно стереть ваши данные.В то время как пропущенный идентификатор в единственном числе вернет не найденный маршрут 404.

Для дальнейшего расширения примера, если API должен был выставлять несколько школ, то что-то вроде

УДАЛИТЬ на / school / abc / ученики удалит всех учеников в школе abc.

Выбор правильного слова иногда является проблемой сам по себе, но мне нравится сохранять множественность для коллекции.Например, cart_items или cart/items чувствует себя хорошо.В отличие от удаления cart, удаляется сам объект корзины, а не элементы внутри корзины;).

0 голосов
/ 04 октября 2018

Как насчет:

/resource/ (не /resource)

/resource/ означает, что эта папка содержит нечто, называемое «ресурс», это папка «resouce».

А также я думаю, что соглашение об именах таблиц базы данных такое же, например, таблица с именем 'user' является "таблицей пользователя", она содержит нечто, называемое "user".

0 голосов
/ 01 декабря 2017

Я предпочитаю использовать как множественное число (/resources), так и единственное число (/resource/{id}), потому что я думаю, что оно более четко разделяет логику между работой над сбором ресурсов и работой над одним ресурсом.

Важным побочным эффектом этого может быть также предотвращение неправильного использования API.Например, рассмотрим случай, когда пользователь ошибочно пытается получить ресурс, указав Id в качестве параметра, подобного следующему:

GET /resources?Id=123

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

С другой стороны, при использовании формы единственного числа:

GET /resource?Id=123

сервер, скорее всего, вернет ошибку, потому что идентификатор не указан правильно, и пользователь будет иметьосознать, что что-то не так.

Добро пожаловать на сайт PullRequest, где вы можете задавать вопросы и получать ответы от других членов сообщества.
...