Маршрути та CRUD
Маршрути — це точки входу вашого API. Вони згруповані за ресурсом, і ви можете писати їх вручну або генерувати їх з моделі.
Визначення маршруту
Section titled “Визначення маршруту”Маршрут несе метод, шлях, параметри та відповіді. Шлях
використовує синтаксис {{param}} від Restorm: щойно ви вводите {{id}} у шлях,
з’являється відповідний параметр; його вилучення видаляє параметр.
Параметри
Section titled “Параметри”Вкладка Визначення маршруту перелічує його параметри — параметри шляху
(створені з плейсхолдерів {{param}}) і параметри запиту / заголовка, які ви
додаєте через Додати параметр. Кожен несе назву, розташування (in),
ознаку обов’язковості, опис і, за бажанням, приклад.
Комірка Тип — це комбо: виберіть примітив (string, integer, number,
boolean) або один з іменованих enum-ів дизайну одним кліком. Для складніших
випадків виберіть Advanced…, щоб відкрити невелике вікно, де ви можете:
- зробити параметр масивом і вибрати його тип елемента (
array<string>, …) — багатозначний параметр запиту; - надати йому вбудовані значення enum-у (дозволений набір, перелічений у вигляді бейджів), коли він не типізований іменованим enum-ом;
- Витягнути в іменований enum — підвищити ці вбудовані значення до спільного enum-у (див. Моделі та enum-и).
Параметр також можна прив’язати до властивості моделі (колонка Зв’язок з моделлю), від якої він успадковує тип, або позначити застарілим. Кожен параметр — його тип, його enum, його застарілість — потрапляє до згенерованої документації і в кожну проєкцію протоколу.
Згенерувати CRUD
Section titled “Згенерувати CRUD”З налаштувань моделі Згенерувати CRUD одним кліком створює групу маршрутів, названу за множиною моделі, з шістьма маршрутами:
| Маршрут | Метод і шлях | Відповіді |
|---|---|---|
| Список | GET / (з пагінацією) | 200 |
| Отримати | GET /{{id}} | 200 · 404 |
| Створити | POST / | 201 |
| Замінити | PUT /{{id}} | 200 · 404 |
| Оновити | PATCH /{{id}} | 200 · 404 |
| Видалити | DELETE /{{id}} | 204 · 404 |
Список має пагінацію (offset, 20 елементів за замовчуванням, 100
максимум). Кожен {{id}} автоматично пов’язаний з ідентифікатором моделі.
Діалогове вікно Згенерувати CRUD пропонує два варіанти:
- Замінити наявні маршрути — щоб уникнути дублікатів, якщо ви генеруєте повторно.
- Захистити маршрути запису автентифікацією — створення, заміна, оновлення та видалення вимагають тоді токен (bearer), тоді як читання залишаються публічними.
Воно також нагадує, що CRUD віддається в кожному протоколі: маршрути REST, запити та мутації GraphQL, методи gRPC, набір сутностей OData та операції SOAP (див. Віддавання проєкту як mock).
Згенерувати маршрути пошуку
Section titled “Згенерувати маршрути пошуку”Для кожної властивості, позначеної як searchable, Згенерувати маршрути пошуку додає параметр запиту, пов’язаний з маршрутом списку моделі (і створює цей маршрут, якщо його ще не існує).
Автентифікація
Section titled “Автентифікація”Автентифікація налаштовується на трьох рівнях: значення за замовчуванням проєкту, обов’язкова автентифікація на рівні групи, і перевизначення на рівні маршруту (яке успадковує значення за замовчуванням групи). Доступні режими: Немає, Bearer (JWT), Ключ API (заголовок) і Basic.
Теги групують маршрути для документації та експорту OpenAPI. Вони існують на двох рівнях: маршрут несе власні теги (його вкладка Визначення), а група несе спільні теги (її налаштування), застосовані до кожного її маршруту. Дієві теги маршруту — це об’єднання обох, тож тег, спільний для цілої групи, краще задати один раз на групі. Коли ви перетворюєте імпортований API на дизайн, тег, присутній на всіх маршрутах групи, автоматично піднімається на групу.
Застарілість
Section titled “Застарілість”Маршрут (як і властивість чи параметр) можна позначити застарілим з його
Налаштувань. Застарілий маршрут відображається сірим у списку Маршрутів і
в згенерованих клієнтах, а на його вкладці з’являється попередження про
застарілість. Прапорець поширюється в кожну проєкцію протоколу — deprecated в
OpenAPI, директива @deprecated у GraphQL, дескриптори SOAP і gRPC, і метадані
OData — щоб споживачі будь-якого віддаваного протоколу його бачили.