✔️ REST API Метод подтверждения заявки - правильный ответ PATCH

В комментариях Алексей объяснил, почему логичным выглядит именно PATCH:
PATСН выглядит логичным, если на самом деле имеется в виду изменение статуса существующей заявки.

------
Прилетает запрос PATCH на endpoint вида
PATCH /api/v1/orders/{orderId}
В теле запроса идет JSON в духе
{ "orderStatus": "accepted" }.

В ответ на запрос возвращаем 200 OK с JSON с полным набором ключей и значений.
------

Почти полностью согласна с Алексеем, который написал в комментариях пояснение:

------
Прилетает запрос PATCH на endpoint вида
PATCH /api/v1/order/{orderId}/confirm
или
PATCH /api/v1/order/{orderId}/changeStatus
или
PATCH /api/v1/order/{orderId}/changeStatus

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

В ответ на запрос возвращаем 200 OK с JSON с полным набором ключей и значений.
------

Мы выбираем PATCH, а не PUT или POST, так как по логике работы системы я, как системный аналитик, закладываю:


1. Менеджер подтверждает существующую заявку пользователя - изменяет ее статус с new на confirmed (approved).
То есть создания нового объекта данных нет. Есть изменение существующей заявки, которую ранее создал клиент автосервиса, и дополнение ее данными собранными в звонке от клиента, при необходимости.


2. Для изменения я выбираю PATCH, а не PUT, потому что нужно частичное изменение ресурса - объекта данных "Заявка". Возможно после звонка надо будет только статус поменять и всё, а тело запроса JSON останется пустым в моем примере метода API.


Многие проголосовали за POST. Почему это тоже может быть верно?
Продолжение скоро 🔽

❓ Многие проголосовали за POST. Почему?


3. Можно было бы взять POST в случае если:
1️⃣ Когда клиент оставляет заявку, создается черновик - объект данных "Черновик заявки" / "Запрос клиента" / "...".
2️⃣ Когда менеджер подтверждает созданный клиентом черновик, на уровне БД создается новая сущность "Заявка" на основе данных из "Черновик заявки".
Так как идет создание нового объекта данных, то правильно использовать POST.
Вижу дизайн так:
POST /api/v1/order/{draftId}
Ответ на запрос - HTTP-201 - заявка создана.
Как один из возможных вариантов.

POST может работать в этом контектсе и может быть правильным ответом. Но я склоняюсь к PATCH, т.к. не хочу лишние сущности.

PUT на создание записи в БД в этой задаче не рекомендую использовать, т.к. поддержка оффлайн режима, генерация уникальных идентификаторов на клиенте и идемпотентность здесь не нужны. Но это отдельная большая история... 🙂


Есть еще предложения по решению этой задачи - комментарии! А еще варианты решений точно есть 🙂

Одним из таких "новых уровней" для системного аналитика может стать освоение навыка проектирования REST API.

Звучит сложно 🙁 Ну да, может быть. Но подумаем о вариантах - можно остаться в зоне комфорта, или можно принять вызов и поднять свои навыки на новый уровень.

Каждый новый навык, который ты приобретаешь, это вложение в себя и твою карьеру. Это - инвестиция, которая с большой вероятностью окупится в будущем. Не говоря уже о том, что освоение новых хард-скилов (технических навыков) открывает возможность работы в новых крутых проектах, позволяет более уверенно чувствовать себя в срее разработчиков и просто делает тебя лучше 💪

Чтобы помочь вам сделать шаг в освоении REST API, уже в эту среду мы проведем бесплатный мастер-класс:

🌐 REST API за вечер: от концепции до Postman
🗓 26 июля (СР) в 19:00 Мск
🟢 РЕГИСТРАЦИЯ БЕСПЛАТНЫЙ НА МАСТЕР-КЛАСС

Отбрасывй сомнения и регистрируйся на мастер-класс! Это отличный шанс познакомиться с новым навыком, получить базовые знания и сразу же применить их на практике 🤝

Суть профессионального роста - постоянно двигаться вперед, не бояться нового и стараться быть лучше каждый день. Быть лучшей версией себя каждый новый день 🎯

Продолжим работу с проектом PorscheLab. Давайте разберем, как сделать дизайн одного REST API метода: создать заявку на обслуживание автомобиля в автосервисе.

1️⃣ Первое, с чем определяемся - кто клиенты метода. Заявки будут создавать как незарегистрированные пользователи, так и менеджеры.

У незарегистрированных пользователей я пока предполагаю максимально упрощенную форму заявки. Причина в том, что заявку на сайте важно собрать быстро, не напрягая пользователя. А при ее подтверждении менеджер уточнит всю информацию, точные данные про автомобиль и другие детали, которые могут понадобиться.

А вот если заявку создает менеджер, то он сразу максимально старается собрать информацию про автомобиль.

Поэтому, чтобы было интересно, проектируем метод создания заявки для менеджера. Он будет использоваться для веб-приложения менеждера в CRM Автосервиса.

P.S. Хотела сразу подмешать в этот метод возможность через него же создавать заявку со стороны сайта, но потом осознала боли, с которыми столкнусь:
- Придется добавить ролевую модель на этот метод API, и возможно придется на отдельные поля писать логику с ограничениями. Это усложнение. Придерживаемся принципа - проще = лучше.
- При обсуждении БД мы увидели два варианта реализации. Заявка от пользователя может быть сущностью "Черновик", на основании которой потом создается сущность "Заявка" со структурированной информацией.
Так что смешивать не будем.


2️⃣ Пермиссии - права доступа

Благодаря пункту 1 и объяснению, почему не стоит делать один метод для сайта и для приложения менеджера, определились, что он будет доступен только менеджеру. И администратору системы.

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

Итого, метод доступен

для приложений:
+ веб-приложения менеджера (CRM).

для пользователей:
+ менеджер,
+ администратор.

Это требования работе авторизации для метода. Указание приложений важно, если будем авторизовывать по протоколу OAuth 2.0.

Продолжение скоро🔽

3️⃣ Делаем дизайн: тип метода и URL

Создать = POST
Заявка = request = order (мне больше нравится order - заказ)
А в базе данных у нас вообще appointment. Это ок. Хороший пример для маппинга и напоминания, что лучше использовать единый язык, и делать названия объектов и полей в БД и в API единообразно.

Сайт, который уже есть у автосервиса:
porschelab.com
Для CRM возьмем домен
crm.porschelab.com

Создавать заявки можно только в онлайн. Поэтому никакие идентификаторы и дополнительные параметры в URL не добавляем.

Версия API - 1.0

Получаем:
POST https://crm.porschelab.com/api/1.0/order
Метод создания заявки на обслуживание автомобиля.


4️⃣ Делаем дизайн: JSON для запроса

Для создания заявки нам надо получить информацию о клиенте и автомобиле, о времени и сервисе(-ах), на который записывается клиент.

Структуру JSON вижу так:

{
ID заявки,
Номер заявки,
Дата и время записи,
Клиент (с его параметрами),
Авто (с его параметрами),
Список сервисов, которые выбрал клиент
}


Теперь этот текстовый вид преобразую по шагам в реальный JSON, используя тестовые данные для его демонстрации:

{
"id": "176ca88d-caf3-4db2-b27b-70442f6ac75e",
"number": 1234,
"time": "2023-08-01T12:00Z03",
"client":
{
"id": "f93a566e-f2e2-4623-9f81-59d23d1695f1",
"firstname": "John",
"lastname": "Smith",
"birthday": "1990-08-14",
...
},
"auto": {...}
...
}

Почему зачеркнула id и number? Ответы в комментарии 👀

Вчера в прямом эфире мы сделали Postman-документацию - описали три метода для управления данными об автомобиле.

Дополнила ее информацией и примерами по всем методам, доделала небольшие описания к документации и... Получилось 😍

И это всего лишь три метода и первое знакомство с тем, что из себя представляет полноценная постановка задачи на бэкенд!

А что если взять, и сделать полный проект:
✔️ 10+ методов
✔️ Документация Confluence
✔️ Документация Postman с тестами
✔️ Документация Swagger
✔️ Настроенная авторизация Token / OAuth 2.0
Звучит внушительно. И это реально сделать всего за 2 месяца!

1 АВГУСТА начинается предобучение на практическом курсе для системных и бизнес-аналитиков:

🌟 Дизайн REST API

9 живых вебинаров до 1 октября. В таком формате обучения больше не будет! Это возможность получить максимум живой практики сейчас и уже к Новому году открыть новые карьерные возможности 🤝

Вы с нуля, от БД до документации, пройдете путь аналитика по работе с REST API. По итогам у вас будут личные проекты, которые можно использовать для портфолио ⚡️ Смотрите какие результаты у вас уже после мастер-класса!

Есть цель идти вперед в системном анализе? Встречаемся на практике по REST API в августе! 🙌