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

Question

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

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

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

Answer 1

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

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) 

Answer 2

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

Answer 3

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

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

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

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

Answer 4

Plural

• Простой - все 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 - удаляет spЭфирный ресурс

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

Answer 5

Singular

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

например. CustomerAddress over CustomerAddresses

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

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

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

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

Class Mapping

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

Подробнее о Дилемма разработчика REST API

Answer 6

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

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

Answer 7

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

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

Answer 8

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

См 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)

Answer 9

С точки зрения потребителя 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 в моем коде?

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

Answer 10

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

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

/ customer / 1

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

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

/ equipment / 1

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