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

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

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

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

Предпосылка использования /resourcesзаключается в том, что он представляет «все» ресурсы. Если вы сделаете это GET /resources, вы, скорее всего, вернете всю коллекцию. Размещая в /resources, вы добавляете в коллекцию.

Тем не менее, отдельные ресурсы доступны в / ресурс. Если вы сделаете a GET /resource, вы, скорее всего, ошибетесь, так как этот запрос не имеет никакого смысла, тогда как /resource/123имеет смысл.

Использование /resourceвместо /resourcesаналогично тому , как вы могли бы сделать это , если вы работали с, скажем, файловой системы и набора файлов и /resourceявляется «каталог» с отдельными 123, 456файлы в нем.

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

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

GET  /orders          <---> orders 
POST /orders          <---> orders.push(data)
GET  /orders/1        <---> orders[1]
PUT  /orders/1        <---> orders[1] = data
GET  /orders/1/lines  <---> orders[1].lines
POST /orders/1/lines  <---> orders[1].lines.push(data) 

Я не вижу смысла в этом, и я думаю, что это не лучший дизайн URI. Как пользователь службы RESTful, я бы ожидал, что ресурс списка будет иметь одно и то же имя, независимо от того, получу ли я доступ к списку или к конкретному ресурсу «в» списке. Вы должны использовать одни и те же идентификаторы, независимо от того, хотите ли вы использовать ресурс списка или конкретный ресурс.

множественное число

• Все просто - все URL начинаются с одинакового префикса
• Логический - orders/получает индекс списка заказов.
• Стандарт - наиболее распространенный стандарт, за которым следует подавляющее большинство публичных и частных API.

Например:

GET /resources - возвращает список элементов ресурса

POST /resources - создает один или несколько элементов ресурса

PUT /resources - обновляет один или несколько элементов ресурса

PATCH /resources - частично обновляет один или несколько элементов ресурса

DELETE /resources - удаляет все элементы ресурса

И для отдельных ресурсов:

GET /resources/:id- возвращает конкретный элемент ресурса на основе :idпараметра

POST /resources/:id - создает один элемент ресурса с указанным идентификатором (требуется проверка)

PUT /resources/:id - обновляет определенный элемент ресурса

PATCH /resources/:id - частично обновляет определенный элемент ресурса

DELETE /resources/:id - удаляет определенный элемент ресурса

Для сторонников единственного числа, подумайте об этом так: вы бы попросили кого-то за orderи ожидали одну вещь или список вещей? Так почему вы ожидаете, что сервис вернет список вещей при вводе /order?

Единственное число

удобство Вещи могут иметь неправильные имена во множественном числе. Иногда их нет. Но имена в единственном числе всегда есть.

например, CustomerAddress поверх CustomerAddresses

Рассмотрим этот связанный ресурс.

Это /order/12/orderdetail/12более читабельно и логично, чем/orders/12/orderdetails/4 .

Таблицы базы данных

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

Отображение классов

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

Узнайте больше о дилемме разработчика REST API

В то время как наиболее распространенной практикой является API RESTful, где используется множественное число, например /api/resources/123, есть один особый случай, когда я нахожу использование единственного имени более подходящим / выразительным, чем множественное число. Это случай отношений один-к-одному. В частности, если целевой элемент является ценностным объектом (в парадигме управляемой доменом разработки).

Давайте предположим, что каждый ресурс имеет взаимно-однозначное отношение, accessLogкоторое может быть смоделировано как объект значения, т. Е. Не объект, следовательно, не ID. Это может быть выражено как /api/resources/123/accessLog. Обычные глаголы (POST, PUT, DELETE, GET) надлежащим образом выражают намерение, а также тот факт, что отношения действительно взаимно-однозначные.

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

Дилемма именования таблиц: единственные и множественные имена

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

Видеть Http://web2.uvcs.uvic.ca/elc/studyzone/330/grammar/irrplu.htm.

Существует много типов нерегулярного множественного числа, но они являются наиболее распространенными:

Тип существительного Формирование множественного числа Пример

Ends with -fe   Change f to v then Add -s   
    knife   knives 
    life   lives 
    wife   wives
Ends with -f    Change f to v then Add -es  
    half   halves 
    wolf   wolves
    loaf   loaves
Ends with -o    Add -es 
    potato   potatoes
    tomato   tomatoes
    volcano   volcanoes
Ends with -us   Change -us to -i    
    cactus   cacti
    nucleus   nuclei
    focus   foci
Ends with -is   Change -is to -es   
    analysis   analyses
    crisis   crises
    thesis   theses
Ends with -on   Change -on to -a    
    phenomenon   phenomena
    criterion   criteria
ALL KINDS   Change the vowel or Change the word or Add a different ending   
     man   men
     foot   feet
     child   children
     person   people
     tooth   teeth
     mouse   mice
 Unchanging Singular and plural are the same    
     sheep deer fish (sometimes)

С точки зрения потребителя API конечные точки должны быть предсказуемыми, поэтому

Идеально...

1. GET /resources должен вернуть список ресурсов.
2. GET /resource должен вернуть код состояния 400 уровня.
3. GET /resources/id/{resourceId} должен вернуть коллекцию с одним ресурсом.
4. GET /resource/id/{resourceId} должен вернуть объект ресурса.
5. POST /resources должен пакетно создавать ресурсы.
6. POST /resource должен создать ресурс.
7. PUT /resource должен обновить объект ресурса.
8. PATCH /resource следует обновить ресурс, разместив только измененные атрибуты.
9. PATCH /resources следует пакетно обновить ресурсы, публикуя только измененные атрибуты.
10. DELETE /resourcesследует удалить все ресурсы; шучу: код статуса 400
11. DELETE /resource/id/{resourceId}

Этот подход является наиболее гибким и многофункциональным, но он также требует больше времени для разработки. Так что, если вы спешите (что всегда имеет место при разработке программного обеспечения), просто назовите свою конечную точку resourceили форму множественного числа resources. Я предпочитаю единственную форму, потому что она дает вам возможность анализировать и оценивать программно, поскольку не все формы множественного числа заканчиваются на «s».

Сказав все это, по любой причине, которую выбрал наиболее часто используемый разработчик практики, это использовать форму множественного числа. Это в конечном итоге маршрут, который я выбрал, и если вы посмотрите на популярных API-интерфейсов, githubи twitterэто то, что они делают.

Некоторые критерии для принятия решения могут быть:

1. Какие у меня временные ограничения?
2. Какие операции я позволю своим потребителям делать?
3. Как выглядит запрос и результат?
4. Хочу ли я иметь возможность использовать отражение и анализировать URI в моем коде?

Так что решать вам. Просто будь последовательным.

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

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

Я предпочитаю использовать единственную форму для простоты и последовательности.

Например, учитывая следующий URL:

/ Клиент / 1

Я буду относиться к клиенту как к коллекции клиентов, но для простоты часть коллекции удалена.

Другой пример:

/ Оборудование / 1

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

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

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

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

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

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

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

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

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

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

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

Посмотрите на Google «s API Design Guide: Resource Names для других взять на себя называющие ресурсах.

Короче говоря:

• Коллекции названы множественным числом.
• Отдельные ресурсы именуются со строкой.

|--------------------------+---------------+-------------------+---------------+--------------|
| 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   |
|--------------------------+---------------+-------------------+---------------+--------------|

Это стоит прочитать, если вы думаете об этом предмете.

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

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

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

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

Мое соглашение заключается в том, что каждый уровень глубины в 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

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

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

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

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

Мне не нравится, когда {id}часть URL-адресов пересекается с подресурсами, какid теоретически может быть что угодно, и возникнет неоднозначность. Он смешивает разные понятия (идентификаторы и имена подресурсов).

Подобные вопросы часто рассматриваются в enumпостоянных или папки структур, где разные понятия смешиваются (например, когда у вас есть папки Tigers, Lionsи Cheetahs, а затем также папка Animalsна том же уровне - это не имеет никакого смысла , так как один является подмножеством Другой).

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

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

GET  /user             -> Not allowed, 400
GET  /user/{id}        -> Returns user with given id
POST /user             -> Creates a new user
PUT  /user/{id}        -> Updates user with given id
DELETE /user/{id}      -> Deletes user with given id

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

GET /users             -> Lists all users, optionally filtered by way of parameters
GET /users/new?since=x -> Gets all users that are new since a specific time
GET /users/top?max=x   -> Gets top X active users

А вот несколько примеров подресурса, который имеет дело с конкретным пользователем:

GET /user/{id}/friends -> Returns a list of friends of given user

Завести друга (многие ко многим):

PUT /user/{id}/friend/{id}     -> Befriends two users
DELETE /user/{id}/friend/{id}  -> Unfriends two users
GET /user/{id}/friend/{id}     -> Gets status of friendship between two users

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

Используйте Singular и пользуйтесь английским соглашением, например, в «Business Directory».

Многие вещи читают таким образом: «Книжный шкаф», «Собачья стая», «Художественная галерея», «Кинофестиваль», «Автомобильный лот» и т. Д.

Это удобно соответствует пути URL слева направо. Тип элемента слева. Установите тип справа.

GET /usersДействительно ли когда-нибудь выбирают группу пользователей? Как правило, не. Он выбирает набор заглушек, содержащих ключ и, возможно, имя пользователя. Так что это не совсем /usersтак. Это индекс пользователей, или «пользовательский индекс», если хотите. Почему бы не назвать это так? Это /user/index. Так как мы назвали тип набора, у нас может быть несколько типов, показывающих различные проекции пользователя, не прибегая к параметрам запроса, например, user/phone-listили /user/mailing-list.

А как насчет пользователя 300? Это все еще /user/300.

GET /user/index
GET /user/{id}

POST /user
PUT /user/{id}

DELETE /user/{id}

В заключение, HTTP может иметь только один ответ на один запрос. Путь всегда относится к чему-то единственному.

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

Сбор позволяет методами GET / POST / DELETE

Пункт позволяет методы GET / PUT / DELETE

Например

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

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

DELETE on / student / 123 удалит ученика 123 из школы.

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

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

DELETE on / school / abc / Students удалит всех учеников в школе abc.

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

Как насчет:

/resource/(нет /resource)

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

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

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

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

GET /resources?Id=123

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

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

GET /resource?Id=123

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