Продолжим работу с проектом 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 в августе! 🙌

⚡️ Начинаем через 15 мин ⚡️

📹 REST API за вечер: от концепции до Postman
Подключайтесь по ссылке: https://pruffme.com/webinar/?id=6d3216bb459b3d4f864904e818ed46fc

Новосибирск, Казахстан, Бали и не только - подключаемся ❤️

⚡️ Вебинарная комната на повтор мастер-класса⚡️

📹 REST API за вечер: от концепции до Postman
Подключайтесь по ссылке: https://pruffme.com/webinar/?id=6d3216bb459b3d4f864904e818ed46fc

СЕГОДНЯ, ВСК:
30 июля, 15:00 Мск
30 июля, 19:00 Мск

⚡️ Что должен содержать URL в REST API? ⚡️

URL или эндпоинт REST API играет важную роль, так как он определяет метод (ресурс / объект данных), к которому выполняется запрос.

Рекомендации на примере, которые стоит сохранить и использовать. Разберем URL метода получения информации об автомобиле для нашего автосервиса PorscheLab.

------------------------
GET htttps://www.PorscheLab.com/api/public/v1/auto/{autoId}
------------------------

🗝 GET - тип метода.
Это не часть URL. В идеале он должен забирать на себя глагол действия по CRUD-модели. Создать авто (тип метода POST), изменить данные об авто (тип метода PATCH) и другие.

🗝 htttps - протокол.
Обычно это "http" или "https", которые определяют способ передачи данных между клиентом и сервером. "https" обеспечивает защищенное соединение с помощью шифрования.

🗝 www.PorscheLab.com - доменное имя (или IP-адрес).
Это адрес сервера, на котором размещается REST API. Например, "api.example.com" или "192.168.1.100".

🗝 /api - путь к ресурсу, имя каталога на сервере.
Представьте, что отсюда начинается путь к папке в компьютере. api указывает, что мы обращаемся к методам АПИ на сервере. Этот указатель в пуи полезен, когда на этом же адресе также работает и сайт системы.
Рекомендовано указывать, но не обязательно.

🗝 /public - путь к ресурсу, имя папки с группой API или сервиса на сервере.
Это имя сервиса или группы методов API. Нпример, в примере я указала, что буду работать с public - методами публичного API в системе. А можно также работать с методами приватного API, либо обращаться к API платженого микросервиса в системе /billing-service.
Рекомендовано указывать, но не обязательно.


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

Боль с кодами ошибок HTTP для REST API 🥲

Проектирование REST API - это не просто о создании запросов. Это о разработке целостной системы, включая варианты ответов на запросы. Нужно включать аналитическое мышление и прорабатывать варианты ответов на запрос: не только успех, но и возможные ошибки.

🌟 Разработка требований к обработке ошибок в REST API оказалась по опыту одной из самых важных и нужных тем к освоению.

Работа аналитика заключается в этом - продумать, какие могут быть возможные варианты работы системы. Он должен учитывать все возможные сценарии, включая альтернативные

Это не тестеровщики задают требования к обработке ошибок. Это наша аналитическая работа – тщательно продумать алгоритмы и подготовить требования к обработке ошибок, по которым они будут тестировать Backend через Postman.

Познакомимся с основными кодами ответов HTTP? 😏🔥

P.S. Самый нужный в картинке к посту.
Коллеги, у нас 418-ая! 😄

‼️ Статусы HTTP для ответов на запросы REST API ‼️
которые должен знать каждый системный аналитик и разработчик

HTTP-200: "ОК".
Успешное выполнение запроса. Используется преимущественно для GET, PUT, PATCH.

HTTP-201: "Создано".
Обычно возвращается для POST и PUT после успешного создания нового ресурса - записи данных в таблицу БД.

HTTP-400: "Плохой запрос".
Запрос не может быть обработан из-за неверного синтаксиса - формата запроса. Ошибка на стороне клиента. Например, в номере счета содержится буква или длина фамилии в запросе больше 128 символов, а ожидалось до 128.
Может сопровождаться красивым текстом сообщением, которое можно показать пользователю.

HTTP-401: "Неавторизован".
Запрос требует аутентификации пользователя, то есть выполняется приложением или пользователем без авторизации (логина+пароля или ключа доступа в виде токена).

HTTP-403: "Запрещено".
Сервер понял запрос, но он отказывается его выполнять. Как правило это связано с тем, что пользователь авторизован, но доступ запрещен - настройка прав доступа к API.

HTTP-404: "Не найдено".
Сервер не может найти запрашиваемый ресурс - данные в БД не найдены.

HTTP-500: "Внутренняя ошибка сервера".
Возникает, когда сервер столкнулся с ситуацией, которую он не знает как обработать. Ошибка в работе алгоритма.
Может сопровождаться красивым текстом сообщением, которое можно показать пользователю.

HTTP-503: "Сервис недоступен".
Сервер временно не может обрабатывать запросы по техническим причинам.


⚠️ Помните, что для каждого из этих кодов можно предусмотреть несколько вариантов сообщений в зависимости от конкретных условий или ошибок. Это важно учитывать при проектировании REST API и анализе поведения системы.

И ответ на самый распространенный вопрос:
если обработку ошибок не заложить в требования, то сама она автоматически не появится. Увы 😄

Уже сегодня у нас с группой по REST API начинается предобучение. А на следующей неделе пройдет первый практический вебинар, на котором мы вместе начнем проект с нуля и проведем его от требований+БД до создания всех рабочих методов API на заглушках в Postman и Swagger-документации 🗝

Рада видеть всех, кто присоединился к проекту 🚀 Спасибо вам за доверие! В начале сентября будем подробно разбирать эту часть на практике 🤝