Керівництво з найменування REST ресурсів

Керівництво з найменування REST ресурсів

09.08.2018 12:05 | Інше

Примітка: ця стаття є перекладом. Оригінал можна почитати тут.

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

Ресурс може бути одним елементом або колекцією. Наприклад, customers (клієнти) - це ресурс-колекція, а customer (клієнт) - ресурс-елемент. Ми можемо ідентифікувати ресурс колекції customers, використовуючи URI /customers, а ресурс одного клієнта customer за допомогою URI /customers/{customerId}.

Ресурс може містити вкладені колекції. Наприклад, вкладена колекція accounts конкретного клієнта (customer) може бути ідентифікована з використанням URI /customers/{customerId}/accounts. Аналогічним чином, одноелементний ресурс account, що знаходиться у вкладеному ресурсі accounts можна визначити наступним чином: /customers/{customerId}/accounts/{accountId}.

Для управління ресурсами REST API використовує URI (уніфіковані ідентифікатори ресурсів). Розробники REST API повинні створювати URI, які чітко передають модель ресурсів потенційним розробникам клієнтських додатків. Коли ресурси названі добре, API є інтуїтивно зрозумілим і простим у використанні. Якщо ж це буде зроблено погано, API може виявитися незрозумілим та незручним у використанні.

Обмеження одноманітного інтерфейсу частково усувається комбінацією URI і HTTP-дієслів, і використовує їх відповідно до стандартів і угод.

Нижче наведено кілька рекомендацій, які допоможуть Вам при створенні URI для вашого нового API.

Найкращі практики найменування REST ресурсів

Використовуйте іменники для представлення ресурсів

RESTful URI повинен посилатися на ресурс, який є предметом (іменником), а не посиланням на дію (дієсловом), оскільки іменники мають властивості, яких немає у дієслів - подібно до того, як у ресурсів є деякі атрибути. Кілька прикладів ресурсів:

  • користувачі системи
  • акаунти користувачів
  • мережеві пристрої і т.д.

URI їх ресурсів можуть виглядати так, як показано нижче:

http://api.example.com/device-management/managed-devices 
http://api.example.com/device-management/managed-devices/{device-id} 
http://api.example.com/user-management/users/
http://api.example.com/user-management/users/{id}

 

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

Документ

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

Використовуйте ім'я в однині для позначення архетипу ресурсу документа:

http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users/{id}
http://api.example.com/user-management/users/admin

 

Колекція

Ресурс-колекція (колекція ресурсів) - це керований сервером каталог ресурсів. Клієнти можуть пропонувати нові ресурси для додавання в колекцію. Проте, колекція сама визначає, створювати новий ресурс, чи ні. Ресурс-колекція вибирає те, що хоче включати, а також визначає, яким буде URI кожного ресурсу, що міститься в ній.

Використовуйте назву в множині для позначення архетипу ресурсу-колекції:

http://api.example.com/device-management/managed-devices
http://api.example.com/user-management/users
http://api.example.com/user-management/users/{id}/accounts

 

Сховище

Сховище являє собою керований клієнтом репозиторій ресурсів. Ресурс сховища дозволяє клієнту API вставляти ресурси, відтворювати їх і вирішувати, коли їх видаляти. Сховище ніколи не генерує нові URI. Замість цього кожен збережений ресурс має призначений клієнтом URI, який присвоюється, коли ресурс спочатку розміщується в сховищі.

Використовуйте назви в множині для позначення архетипу ресурсу сховища:

http://api.example.com/cart-management/users/{id}/carts
http://api.example.com/song-management/users/{id}/playlists

 

Контроллер

Ресурс-контроллер моделює процедурну концепцію. Контролери схожі на виконувані функції з параметрами і значеннями, що повертаються.

Використовуйте дієслово для позначення архетипу контроллера:

http://api.example.com/cart-management/users/{id}/cart/checkout
http://api.example.com/song-management/users/{id}/playlist/play

 

Послідовність і узгодженість – ключові поняття

Використовуйте угоди про іменування і форматування URI для мінімальної двозначності і максимальної зручності читання і керованості. Ви можете слідувати нижченаведеним порадам для досягнення узгодженості.

1. Використовуйте слеш (/) для позначення ієрархічних відносин

Символ слеша (/) використовується для поділу URI на частини, щоб вказати ієрархічний взаємозв'язок між ресурсами. Наприклад:

http://api.example.com/device-management
http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices/{id}
http://api.example.com/device-management/managed-devices/{id}/scripts
http://api.example.com/device-management/managed-devices/{id}/scripts/{id}

 

2. Не використовуйте в URI завершальний слеш

В якості останнього символу в URI слеш не додає ніякого семантичного значення і може викликати плутанину. Краще відмовитися від подібної практики.

http://api.example.com/device-management/managed-devices/
http://api.example.com/device-management/managed-devices   // Ця версія набагато краща

 

3. Використовуйте дефіси для покращення читаності URI

Щоб Ваші URI можна було легко сканувати і інтерпретувати, використовуйте символ дефіса. Так покращитися читаність імен в сегментах довгого шляху.

http://api.example.com/inventory-management/managed-entities/{id}/install-script-location

 

4. Не використовуйте нижні підкреслення (_)

В якості роздільника можна було б використовувати замість дефісу символ підкреслення. Але, залежно від шрифту програми, можливо, що підкреслення (_) можуть бути частково закриті або повністю заховані в деяких браузерах або не відображатися на деяких екранах.

Щоб уникнути цієї плутанини, використовуйте дефіси.

http://api.example.com/inventory-management/managed-entities/{id}/install-script-location  // Добре читається
http://api.example.com/inventory_management/managed_entities/{id}/install_script_location  // Більш схиьний до помилок

 

5. Використовуйте в URI літери в нижньому регістрі

Слід надавати перевагу малим буквах в шляхах. При цьому слід знати, що RFC 3986 визначає URI як чутливі до регістру, за винятком схеми і компонентів хоста.

http://api.example.org/my-folder/my-doc  // 1
HTTP://API.EXAMPLE.ORG/my-folder/my-doc  // 2
http://api.example.org/My-Folder/my-doc  // 3

 

Приклади 1 і 2 є ідентичними. Але шлях в прикладі 3 відрізняється, оскільки використовує великі літери (My-Folder).

6. Не використовуйте розширення файлів

Розширення файлів виглядають погано і не додають ніяких переваг. Видалення їх також зменшує довжину URI. Тому немає причин включати їх в шляхах.

У випадках, коли Ви хочете вказати, як потрібно обробляти контент, не слід виділяти медіа-тип за допомогою розширень, краще передати медіа-тип в заголовку Content-Type.

http://api.example.com/device-management/managed-devices.xml  // Не робіть так
http://api.example.com/device-management/managed-devices      // Коректний URI

 

Ніколи не використовуйте в URI імена CRUD-функцій

URI не повинні використовуватися для вказівки того, що виконується функція CRUD. URI слід використовувати для унікальної ідентифікації ресурсів, а не для будь-яких дій. А для вказівки функції CRUD повинні використовуватися методи HTTP-запиту.

HTTP GET http://api.example.com/devices  // Отримати всі пристрої
HTTP POST http://api.example.com/devices  // Створити новий пристрій

HTTP GET http://api.example.com/devices/{id}  // Отримати пристрій із вказанним Id
HTTP PUT http://api.example.com/devices/{id}  // Поновити пристрій із вказанним Id
HTTP DELETE http://api.example.com/devices/{id}  // Видалити пристрій із вказанним Id

 

Використовуйте компонент запиту для фільтрації колекції URI

Багато разів ви будете стикатися з вимогами, в яких вам знадобиться колекція ресурсів, відсортованих, відфільтрованих або обмежених на основі деякого певного атрибута ресурсу. Для цієї мети не слід створювати нові API - краще включіть функції сортування, фільтрації та розбивки на сторінки в API збору ресурсів і передайте вхідні параметри в якості параметрів запиту. Наприклад:

http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices?region=USA
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ