1. Що таке ресурс?
У REST первинне представлення даних називається ресурсом . Наявність узгодженої та надійної стратегії іменування ресурсів REST стане одним із найкращих проектних рішень у довгостроковій перспективі.
Ключовою абстракцією інформації в REST є ресурс. Будь-яка інформація, яку можна назвати, може бути ресурсом: документом або зображенням, тимчасовою службою (наприклад, «погода в Харкові зараз»), колекцією інших ресурсів, невіртуальним об’єктом (наприклад, людиною) тощо.
Іншими словами, будь-яка концепція, яка може бути ціллю гіпертекстового посилання автора, повинна відповідати визначенню ресурсу.
Ресурс — це концептуальне відображення набору сутностей, а не сутність, яка відповідає відображенню в будь-який конкретний момент часу.— Дисертація Роя Філдінга
1.1. Ресурси Singleton і Collection
Ресурс може бути одиничним елементом або колекцією .
Наприклад, «customers» — це ресурс колекції, а «customer» — одиночний ресурс (у банківському домені).
Ми можемо визначити ресурс колекції «customers» за допомогою URI «/customers». Ми можемо визначити один ресурс «customer» за допомогою URI «/customers/{customerId}».
1.2. Ресурси колекції та підколекції
Ресурс також може містити ресурси підколекції.
Наприклад, ресурс підколекції «accounts» певного «customer» можна ідентифікувати за допомогою URI «/customers/{customerId}/accounts».
Подібним чином, єдиний ресурс «account» всередині ресурсу підколекції «accounts» можна ідентифікувати наступним чином: «/customers/{customerId}/accounts/{accountId}».
1.3. URI
REST API використовує уніфіковані ідентифікатори ресурсів (URI) для адресації ресурсів. Розробники REST API повинні створити URI, які передають модель ресурсів REST API потенційним клієнтам API. Коли ресурси правильно названі, API інтуїтивно зрозумілий і простий у використанні. Якщо зробити невдало, той самий API може бути складним для використання та розуміння.
Обмеження єдиного інтерфейсу частково вирішується за допомогою комбінації URI і HTTP-дієслів і їх використання відповідно до стандартів і конвенцій.
Нижче наведено кілька порад, які допоможуть вам створити URI ресурсів для вашого нового API.
2. Передовий досвід
2.1. Використовуйте іменники для позначення ресурсів
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}Для більшої ясності давайте розділимо архетипи ресурсів на чотири категорії (документ, колекція, сховище та контролер). Тоді було б найкраще, якби ви завжди мали на меті помістити ресурс в один архетип, а потім послідовно використовувати його іменування .
Заради одноманітності утримайтеся від спокуси створити ресурси, які є гібридами більш ніж одного архетипу.
2.1.1. Документ (document)
Ресурс документа — це окреме поняття, схоже на екземпляр об’єкта або запис бази даних.
У REST ви можете переглядати його як окремий ресурс у колекції ресурсів. Представлення стану документа зазвичай включає як поля зі значеннями, так і посилання на інші пов’язані ресурси.
Використовуйте назву «в однині» для позначення архетипу ресурсу документа (device-management, user-management).
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/admin2.1.2. Колекція (collection)
Ресурс колекції — це каталог ресурсів, яким керує сервер.
Клієнти можуть пропонувати нові ресурси для додавання до колекції. Однак ресурс колекції вирішує створити новий ресурс чи ні.
Ресурс колекції вибирає, що він хоче містити, а також вирішує URI для кожного ресурсу, що міститься.
Використовуйте назву «у множині», щоб позначити архетип ресурсу колекції (managed-devices, users, accounts).
http://api.example.com/device-management/managed-devices
http://api.example.com/user-management/users
http://api.example.com/user-management/users/{id}/accounts2.1.3. Сховище (store)
Store— це сховище ресурсів, яким керує клієнт. Ресурс сховища дозволяє клієнту API додавати ресурси, отримувати їх назад і вирішувати, коли їх видалити.
Магазин ніколи не генерує нові URI. Натомість кожен збережений ресурс має URI. URI був вибраний клієнтом, коли ресурс спочатку додав його в магазин.
Використовуйте назву у множині для позначення архетипу ресурсу сховища (song-management).
http://api.example.com/song-management/users/{id}/playlists2.1.4. Контролер (controller)
Ресурс контролера моделює процедурну концепцію. Ресурси контролера схожі на виконувані функції з параметрами та значеннями, що повертаються, входами та виходами.
Використовуйте «дієслово»(play) чи етап дії(checkout) для позначення архетипу контролера.
http://api.example.com/cart-management/users/{id}/cart/checkout
http://api.example.com/song-management/users/{id}/playlist/play2.2. Послідовність – це ключ
Використовуйте узгоджені угоди про іменування ресурсів і форматування URI для мінімальної неоднозначності та максимальної читабельності та зручності обслуговування. Ви можете застосувати наведені нижче поради щодо дизайну, щоб досягти узгодженості:
2.2.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.2.2. Не використовуйте косу риску (/) в кінці URI
Як останній символ у шляху URI, коса риска (/) не додає семантичного значення та може заплутати. Краще не додавати її до URI.
http://api.example.com/device-management/managed-devices/ http://api.example.com/device-management/managed-devices /*Це кращє*/
2.2.3. Використовуйте дефіси (-), щоб покращити читабельність URI
Щоб зробити ваші URI легкими для сканування та інтерпретації, використовуйте символ дефіса (-), щоб покращити читабельність імен у довгих сегментах шляху.
http://api.example.com/devicemanagement/manageddevices/ http://api.example.com/device-management/managed-devices /*Так краще*/
2.2.4. Не використовуйте підкреслення (_)
Замість дефіса можна використовувати підкреслення як роздільник. Але залежно від шрифту програми символ підкреслення (_) може бути частково закритим або повністю прихованим у деяких браузерах або на екранах.
Щоб уникнути цієї плутанини, використовуйте дефіси (-) замість підкреслення (_).
http://api.example.com/inventory-management/managed-entities/{id}/install-script-location //Більш читабельно
http://api.example.com/inventory-management/managedEntities/{id}/installScriptLocation //Менш читабельно2.2.5. Використовуйте малі літери в URI
Якщо немає прямої вимоги користувати різні регістри, у шляхах URI слід віддавати перевагу малим регістрам.
http://api.example.org/my-folder/my-doc //Добре HTTP://API.EXAMPLE.ORG/my-folder/my-doc //Не рекомендуємо http://api.example.org/My-Folder/my-doc //Не рекомендуємо, але можливо це важливо
У наведених вище прикладах 1 і 2 є однаковими, але 3 не є таким, оскільки в ньому використовується ім’я папки My-Folder великими літерами і сервер може розрізняти регістр літер де My-Folder та my-folder це дві різні папки.
2.3. Не використовуйте розширення файлів
Розширення файлів виглядають погано і не додають жодної переваги. Їх видалення також зменшує довжину URI. Немає причин їх тримати.
Окрім зазначеної вище причини, якщо ви хочете виділити тип носія API за допомогою розширення файлу, тоді вам слід покладатися на тип носія, як повідомляється через Content-Type Header, щоб визначити, як обробляти вміст основного вмісту.
http://api.example.com/device-management/managed-devices.xml /*Не робіть так*/ http://api.example.com/device-management/managed-devices /*Це вірний URI*/
2.4. Ніколи не використовуйте імена функцій CRUD в URI
Ми не повинні використовувати URI для позначення функції CRUD (Create, Read, Update, Delete). URI слід використовувати лише для унікальної ідентифікації ресурсів, а не будь-яких дій з ними.
Ми повинні використовувати методи запиту HTTP, щоб вказати, яка функція CRUD виконується.
HTTP GET http://api.example.com/device-management/managed-devices //Get all devices
HTTP POST http://api.example.com/device-management/managed-devices //Create new Device
HTTP GET http://api.example.com/device-management/managed-devices/{id} //Get device for given Id
HTTP PUT http://api.example.com/device-management/managed-devices/{id} //Update device for given Id
HTTP DELETE http://api.example.com/device-management/managed-devices/{id} //Delete device for given Id2.5. Використовуйте компонент запиту для фільтрації колекції 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 http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date