Конвенція REST URI - сингулярне або множинне найменування ресурсу під час його створення

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

• Створення - використання / ресурсів методом POST (спостерігайте за множиною) в деяких місцях, використовуючи / resource (однина)
• Оновлення - за допомогою / ресурсу / 123 методом PUT
• Отримати - Використання / resource / 123 методом GET

Мене трохи не бентежить ця конвенція іменування URI. Що ми повинні використовувати множину чи однину для створення ресурсів? Якими мають бути критерії при вирішенні цього?

Передумова використання /resourcesполягає в тому, що він представляє "всі" ресурси. Якщо ви зробите це GET /resources, ви, ймовірно, повернете всю колекцію. Відправивши на/resources , ви додаєте до колекції.

Однак окремі ресурси доступні на / ресурсі. Якщо ви зробите це 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?

Однини

Зручність У речах можуть бути неправильні назви множини. Іноді їх немає. Але сингулярні імена завжди є.

наприклад, Адреса клієнта через адреси клієнта

Розглянемо цей пов'язаний ресурс.

Це /order/12/orderdetail/12читабельніше і логічніше, ніж/orders/12/orderdetails/4 .

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

Ресурс представляє сутність, як таблиця бази даних. Вона повинна мати логічну назву однини. Ось відповідь над назвами таблиць.

Картографування класів

Заняття завжди поодинокі. Інструменти ORM генерують таблиці з тими ж іменами, що імена класів. По мірі використання все більшої кількості інструментів однини назви стають еталоном.

Детальніше про дилему розробника API REST API

У той час як найбільш поширеною практикою є RESTful apis, де використовуються множини, наприклад /api/resources/123, є один особливий випадок, коли я вважаю, що вживання однини називається більш підходящим / виразним, ніж назви множини. Це справа стосунків один на один. Зокрема, якщо цільовим елементом є об'єкт значення (у парадигмі дизайну, керованого доменом).

Припустимо, що кожен ресурс має індивідуальний, accessLogякий може бути змодельований як об'єкт значення, тобто не сутність, тому немає ідентифікатора. Це можна виразити як /api/resources/123/accessLog. Звичайні дієслова (POST, PUT, DELETE, GET) належним чином виразили б намір, а також факт, що відносини справді є один на один.

Чому б не дотримуватися поширеної тенденції імен таблиць баз даних, де сингулярна форма загальновизнана? Був там, зробив це - давайте повторно використовувати.

Таблиця іменування дилеми: однини проти множини

Я здивований, побачивши, що так багато людей стрибне на множині іменника bandwagon. Виконуючи перетворення однини в множину, чи піклуєтесь ви про іррегулярні іменники множини? Вам подобається біль?

Дивіться 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".

Сказавши все це, з будь-якої причини найбільш часто застосовується розробник практики, це використовувати форму множини. Це в кінцевому підсумку вибраний мною маршрут, і якщо ви подивитеся на популярні апіси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-multiple-resources", якщо саме цього ви хочете. Це насправді не головне.

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

Не намагайтеся зробити його розумнішим, ніж це має бути - перехід від множини до сингулярного залежно від кількості ресурсів, до яких Ви зараз отримуєте доступ, може бути естетично приємним для деяких, але це не ефективно і це не має сенсу в ієрархічна система.

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

Ознайомтеся з керівництвом 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   |
|--------------------------+---------------+-------------------+---------------+--------------|

Варто прочитати, якщо ви думаєте про цю тему.

Використання множини для всіх методів є більш практичним принаймні в одному аспекті: якщо ви розробляєте та тестуєте 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 і скористайтеся англійською конвенцією, що міститься в напр. "Бізнес-довідник".

Багато речей читають так: "Книжковий кейс", "Собака пачок", "Художня галерея", "Кінофестиваль", "Автомобільна партія" тощо.

Це зручно відповідає 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 в / студенти додадуть нового учня в школу.

DELETE on / учні видалять усіх учнів школи.

DELETE on / student / 123 видалить студента 123 зі школи.

Це може здатися неважливим, але деякі інженери іноді забувають ідентифікатор. Якщо маршрут завжди був множинним і виконував DELETE, ви можете випадково стерти свої дані. Якщо відсутній ідентифікатор в однині поверне 404 маршрут, не знайдений.

Для подальшого розширення прикладу, якщо API повинен був виставити кілька шкіл, то щось подібне

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

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

Як щодо:

/resource/(не /resource)

/resource/ означає, що папка містить щось, що називається "ресурс", це папка "повторне використання".

А також я думаю, що умовно-правовий режим імен таблиць баз даних однаковий, наприклад, таблиця під назвою "користувач" - це "таблиця користувача", вона містить щось, що називається "користувач".

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

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

GET /resources?Id=123

У цьому випадку, коли ми використовуємо версію множини, сервер, швидше за все, ігнорує параметр Id і поверне список усіх ресурсів. Якщо користувач не буде обережним, він подумає, що дзвінок був успішним, і використовувати перший ресурс у списку.

З іншого боку, при використанні форми однини:

GET /resource?Id=123

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