REST API дизайн для веб-страниц с мастерами

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

Поэтому я разработал API для параметра запроса action = draft или submit. Если действие является черновым, обязательны только определенные поля. Если действие отправлено, все поля являются обязательными. Проверки в сервисном уровне REST API будут выполняться на основе параметра запроса. Похоже, я должен явно указать условия if / else в документации. Это приемлемая форма дизайна RESTful? Какой будет лучший дизайн с этими требованиями?

Поскольку вы хотите сохранить вещи на сервере между шагами мастера, кажется вполне приемлемым рассматривать каждый шаг как отдельный ресурс. Что-то в этом роде:

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

Включив гиперссылки в ответ, вы можете проинформировать клиента о том, что он может сделать после этого шага - перейти вперёд или назад для промежуточных шагов, и ничего для последнего шага. Вы можете увидеть пример этого на рисунке 5 здесь .

Некоторое время назад мне нужно было сделать нечто подобное, и ниже описывается, чем мы в конечном итоге занимаемся.

У нас есть две таблицы: Item и UnfinishedItem. Когда пользователь заполняет данные с помощью мастера, данные сохраняются в таблице UnfinishedItem. На каждом шаге мастера сервер проверяет данные, введенные на этом шаге. Когда пользователь завершает работу с мастером, мастер отображает скрытую / доступную только для чтения форму на странице подтверждения, которая показывает все данные, подлежащие отправке. Пользователь может просмотреть эту страницу и вернуться к соответствующему шагу, чтобы исправить ошибки. Когда пользователь удовлетворен своими записями, он нажимает кнопку «Отправить», и мастер затем отправляет все данные в скрытых / доступных только для чтения полях формы на сервер API. Когда сервер API обрабатывает этот запрос, он повторно запускает все проверки, которые он выполнял на каждом шаге мастера, и выполняет дополнительные проверки, которые не вписываются в отдельные этапы (например, глобальные проверки, дорогостоящие проверки).

Преимущества двухстолового подхода:

• в базе данных вы можете иметь более жесткие ограничения для таблицы Item, чем для таблицы UnfinishedItem; вам не нужно иметь дополнительные столбцы, которые действительно потребуются после завершения работы мастера.

• Агрегировать запросы по готовым Элементам для отчетности проще, так как вам не нужно помнить, чтобы исключить UnfinishedItems. В нашем случае нам никогда не требовалось выполнять агрегированные запросы между Item и UnfinishedItems, так что это не проблема.

Недостаток:

• Это склонно к дублированию логики проверки. Веб-инфраструктура, которую мы использовали, Django, делает это немного более терпимым, так как мы использовали наследование модели с небольшим количеством мета-магии, чтобы изменить ограничения, которые должны быть разными в Item и UnfinishedItem. Django генерирует большую часть базы данных и формы проверки из модели, и нам нужно только взломать несколько дополнительных проверок поверх этого.

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

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

Я реализовал это способом, подобным сочетанию решений @ guillauma31 и @Lie Ryan.

Вот ключевые понятия:

1. Существует 3 шага мастера, который может быть частично сохранен до завершения.
2. Каждый шаг имеет свой собственный ресурс (например /users/:id_user/profile/step_1,. .../step_2, И т. Д.)
3. На каждом шаге данные и статус завершения могут быть получены с помощью запросов GET и сохранены с помощью запросов PATCH.
4. Каждый ресурс имеет свои правила проверки введенных данных.
5. Каждый шаг возвращает ключ, который необходимо использовать при вводе следующего шага, чтобы гарантировать последовательность. После использования или создания нового токен теряет силу.
6. На последнем шаге у нас есть все необходимые данные в базе данных и отображается экран подтверждения. Это подтверждение вызывает другой ресурс, чтобы пометить данные как завершенные (например:) .../profile/confirm. Этот ресурс не должен получать все данные снова. Он только помечает данные как правильные и полные.
7. Существует запланированная процедура, которая стирает эти неполные записи, которые имеют более нескольких дней.

Ребята из внешнего интерфейса должны позаботиться о жетонах, чтобы заставить работать волшебника туда-сюда.

API не имеет состояния и атомарен.

Чтобы «мастер одного шага» работал с этой настройкой, вам нужно изменить некоторые вещи, такие как удаление потока токенов или создание ресурса для возврата токенов в зависимости от типа мастера, или даже создание нового ресурса только для заполнения этого конкретного шаг мастера (вроде PUT /users/:id_user/profile/).