Дизайн API REST для веб-сторінок з майстрами

11

У мене веб-сторінка з форматом майстра. Кнопка подання в API буде на 4-му кроці майстра. Однак я хочу, щоб введені дані зберігалися в базі даних, перш ніж перейти до наступного кроку майстра. Я також хочу, щоб API REST працював для сторінок, що мають одну вкладку.

Тому я розробив API, щоб здійснити параметр запиту action = проект або подати. Якщо дія чернетка, обов'язкові лише певні поля. Якщо подано дію, усі поля є обов'язковими. Перевірки на рівні обслуговування REST API здійснюватимуться на основі параметра запиту. Схоже, я повинен чітко вказати в документації пункти if / else. Це прийнятна форма RESTful дизайну? Який найкращий дизайн з цими вимогами?

design rest

— TechCrunch
джерело

3

Чому проміжні дані потрібно зберігати в БД?

— Dan1701

2

@ Dan1701: ви можете відновити майстра з іншої машини. Коли ви заповнюєте довгі складні форми, може знадобитися кілька днів, щоб заповнити всі необхідні дані, оскільки користувач може не мати всіх необхідних даних у руці, або користувачеві може знадобитися збирати додаткові файли для завантаження з різних місць. Якщо ви можете відновити роботу з іншого пристрою, ви можете завантажити майстра, щоб завантажити фотографію з мобільного телефону, і продовжувати вводити довгий опис / аргумент за допомогою справжніх клавіатур на робочому столі тощо

— Lie Ryan

У цьому випадку я думаю, що відповідь @ guillaume31 має сенс.

— Dan1701

7

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

POST /wizard/123/step1
POST /wizard/123/step2
POST /wizard/123/step3

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

— guillaume31
джерело

Я використовую Angular для інтерфейсу користувача. Тож я не впевнений, наскільки корисна державна машина. Але я думаю, що крок на основі ресурсу здається більш значущим, ніж управління іншою таблицею. Також я повинен мати можливість подати все за один крок. Сьогодні ми дамо йому знімок на цій конструкції. Дякую за допомогу.

— TechCrunch

Ласкаво просимо. До речі, підхід "двох столів" не взаємовиключний. Наявність одного HTTP-ресурсу за крок не диктує вашу об’єктну модель на сервері додатків, не кажучи вже про схему бази даних. Це просто веб-представлення.

— guillaume31

1

@TechCrunch В основному Гійом означає, що об'єкт / таблицю, що представляє форму, можна розбити на частини, де частина моделі зберігається на кожному кроці. Насправді, ви можете просто мати кожен «крок» бути формою для частини всієї моделі . І якщо взяти такий підхід, це насправді робить архітектуру неймовірно простою. Кожен POST на сервер буде (створювати або) оновлювати одну і ту ж модель, і кожен GET завантажує ту саму модель, і кожен крок буде формою для заповнення наборів полів, що мають семантичне значення (належать разом). І просто мати булеву модель на in_progressабо draft.

— Кріс Сірефіс

3

Мені потрібно було зробити щось подібне деякий час тому, і далі описано, що ми закінчуємо.

У нас є дві таблиці, Item і UnfinishedItem. Коли користувач заповнює дані майстра, дані зберігаються в таблиці UnfinishedItem. На кожному кроці майстра сервер перевіряє дані, введені під час цього кроку. Коли користувач закінчує роботу з майстром, майстер надає приховану форму / лише для читання на сторінці підтвердження, де відображаються всі дані для надсилання. Користувач може переглянути цю сторінку та повернутися до відповідного кроку для виправлення помилок. Після того, як користувач задоволений своїми записами, користувач натискає кнопку "Надіслати", а потім майстер подає всі дані в поля прихованої / лише для читання форми на сервер API. Коли сервер API обробляє цей запит, він повторює всі перевірки, які він робив під час кожного кроку майстра, та виконує додаткові перевірки, які не вписуються в окремі етапи (наприклад, глобальні перевірки, дорогі перевірки).

Переваги двох табличних підходів:

у базі даних ви можете мати більш жорсткі обмеження в таблиці Item, ніж у таблиці UnfinishedItem; вам не потрібно мати додаткові стовпці, які фактично знадобляться після завершення роботи майстра.
Сукупні запити в готових елементах для звітування простіші, оскільки вам не потрібно пам'ятати, щоб виключити UnfinishedItems. У нашому випадку нам ніколи не потрібно було робити сукупні запити між Item і UnfinishedItems, тому це не проблема.

Недолік:

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

Інші можливості, які я розглянув, і чому ми з ними не пішли:

збереження даних у файлах cookie або локальному сховищі: користувач не може продовжувати подання з іншого пристрою або якщо видалити історію браузера
зберігати UnfinishedItem як неструктуровані дані (наприклад, JSON) у базі даних або вторинній сховищі даних: мені доведеться визначити логіку розбору і не можу використовувати автоматичну перевірку моделі / форми Django.
зробіть покрокову перевірку на стороні клієнта: мені доведеться дублювати логіку перевірки між Python / Django та JavaScript.

— Лежать Раян
джерело

1

+1 для вказівки валідацій на «чорнові» моделі та «готові» моделі; Я не думав про це, і це важливий момент, який слід враховувати. Інакше у вас, ймовірно, буде купа ifтверджень, які перевіряють стан чернетки протягом усіх ваших перевірок, що було б просто не добре. Хоча деякі дуже складні рамки, такі як Ruby on Rails, можуть значно спростити цю проблему, якщо її правильно реалізувати.

— Кріс Сірефіс

1

Я реалізував це таким чином, як поєднання рішень @ guillauma31 та @Lie Ryan.

Ось ключові поняття:

Існує триступеневий майстер, який може частково зберігатися до повного завершення.
Кожен крок має свій власний ресурс (наприклад.: /users/:id_user/profile/step_1, .../step_2І т.д.)
На кожному кроці дані та стан завершення можуть бути отримані за допомогою GET-запитів та збережені через PATCH-запити.
Кожен ресурс має власні правила перевірки введених даних.
Кожен крок повертає ключ, який повинен бути використаний при введенні наступного кроку для гарантування послідовності. Щойно використовується або генерується новий, цей маркер закінчується.
На завершальному кроці у нас є всі необхідні дані про базу даних і відображається екран підтвердження. Це підтвердження викликає інший ресурс для позначення даних як закінчених (наприклад:) .../profile/confirm. Цей ресурс не потребує отримання всіх даних знову. Він лише позначає дані як правильні та повні.
Існує запланований режим, який видаляє ці неповні записи, які мають більше кількох днів.

Передні хлопці повинні подбати про жетони, щоб налагодити роботу ходу майстра і назад.

API - без стану та атома.

Щоб змусити "майстра в один крок" працювати з цією установкою, вам доведеться змінити деякі речі, як-от видалити потік маркера або створити ресурс для повернення жетонів на основі типу майстра або навіть створити новий ресурс лише для заповнення цього конкретного синглу крок майстра (як PUT /users/:id_user/profile/).

— Рікардо Суза
джерело