📖 Требования к технической реализации - REST API метод в интеграции 📖

В конце прошлой недели я дала постановку задачи на интеграционный REST API метод:
при удалении задачи в системе #EventTasksGA нужно автоматически удалять её и в системе Todoist.

Но я не обосновала, почему делаю метод:

DELETE /event/{eventId}/task/{taskId} - удаление задачи из мероприятия

Это метод на стороне нашей системы EventTasksGA. Его описывают системные аналитики и/или Backend-разработчики.


Обоснование:

1. DELETE

Этот HTTP-метод выбран, потому что отвечает за удаление.

Ошибки:
❌ Делать

POST /task/{taskId}/delete

или

POST /delete-task/{id}

и т.п.
Не надо тащить глагол действия delete в URL.
Действие удаления выбирается на уровне HTTP-метода.
Аналогично будет с другими действиями.

2. https://test.com/api/v1/event/{eventId}/task/{taskId}

Такой URL выбран, потому что задачи task всегда создаются внутри мероприятий event.

Альтернативные варианты:
👌 /task/{taskId} - т.к. у каждой задачи в системе в любом случае будет свой уникальный id, то не обязательно создавать дополнительную вложенность (мероприятие -> задача)

👌 /task?taskId={id} - можно делать id задачи как query-параметр (после ?), но более распространенная практика использовать path-параметр, как в решении.

Ошибки:
❌ Глагол действия в URL.
❌ Отсутствие id задачи в URL под предлогом, что оно должно быть в body (json).


3. Тело запроса Body (JSON)
Отсутствует.
Вся необходимая информация уже передается в URL.
Также в DELETE обычно не определяют тело запроса (подтверждающий источник).



Чтобы самостоятельно разобраться с проектированием REST API с нуля, рекомендую последовательно познакомиться с материалами:

📚 Протокол HTTP и его связь с REST API
📚 Картинка к посту
📚 Структура постановки задачи на REST API метод
📚 Связь БД и дизайна REST API
📚 Проектирование REST API: спорные вопросы с проектов и собеседований
📚 Вопросы и ответы по REST API: собеседование на системного аналитика


#RestApiGA #ИнтеграцииGA

❌ Работа над ошибками в REST API - часть 1 ❌

А теперь давайте вернемся к посту, где я описала для вас в Confluence подробный интеграционный Use Case.

В нём я указала два интеграционных метода REST API на шагах 4 и 5:

1. POST /orders/{orderId}/projects - создание проекта в системе Todoist для оплаченного заказа на организацию мероприятия.

Мои ошибки:

❌ В предыдущем посте я рассказываю вам, что мы берем для удаления задач DELETE /event/{eventId}/task/{taskId}, а сначала предлагала вместо event использовать в URL сущность order.

❌ В одном случае единственное число (event, task), а в другом множественное (orders, tasks) в названиях сущностей.

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

Поэтому выбираю итоговое решение:
POST /orders/{orderId}/projects
DELETE /orders/{orderId}/tasks/{taskId}

✅ Вместо сущности мероприятие (event) будем использовать заказ (order) везде.
✅ Также будем использовать множественное число для названия эндпоинтов, потому что так привычнее.

2. POST /orders/{orderId}/tasks - создание стандартного набора задач под организацию заказанного мероприятия.

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

❌ Проблемы с иерархией.
C точки зрения внешней системы Todoist задачи должны быть внутри проектов.
А с точки зрения нашей системы задачи нужны для выполнения заказа order.

Получается, что для работы с задачами Todoist должны быть методы:
POST /orders/{orderId}/projects/{projectId}/tasks - создание задачи в проекте
DELETE /orders/{orderId}/projects/{projectId}/tasks/{taskId} - удаление задачи
GET /orders/{orderId}/projects/{projectId}/tasks - список задач проекта в Todoist

Выглядят такие методы перегружено.

Продолжим разбирать "как лучше" в следующем посте 👇

#RestApiGA #ИнтеграцииGA

❌ Работа над ошибками в REST API - часть 2 (читать аккуратно, вдумчиво, глядя на картинку с БД) ❌

Проблемы с иерархией.
C точки зрения внешней системы Todoist задачи рекомендуется делать внутри проектов (API-документация).
А с точки зрения нашей системы задачи нужны для выполнения заказа order.


В БД #EventTasksGA, которую добавила к посту, можно увидеть следующее:

👉 Сущность "Проект Todoist" отсутствует в БД
А в Todoist без проекта нельзя создавать задачи (требование бизнеса).
У нас есть четкое соответствие: для 1 заказа есть 1 проект в Todoist.
Кроме id нам от проекта в Todoist больше ничего не надо в EventTasksGA.
Поэтому давайте только его и хранить в заказе.
Итого: в таблицу order добавляем параметр todolist_project_id. Через него будем узнавать в каком проекте задачи.

👉 Сущность "Задачи Todoist" (todoist_project_task) есть в БД EventTasksGA, и она связана с заказом.
Каждая новая задача в Todoist будет приводить к записи новой задачи в таблицу todoist_project_task - создание новой строки.


После исследований нашей БД и сопоставления с Todoist, предлагаю действовать так:

✅ PATCH /orders/{orderId}/todoist-projects - создание проекта в Todoist под оплаченный заказ, т.е. дополнение таблицы БД “order” параметром project_id.
PATCH - т.к. нет создания новой строки в таблице, а есть только изменение существующей.

✅ POST /orders/{orderId}/tasks - создание задачи в Todoist (вызов API), после чего создаем в БД новую строку - запись о задаче в таблицу todoist_project_task.
POST - так как новая строка данными о задаче в БД.

✅ GET /orders/{orderId}/tasks - список задач по заказу, которые создали в Todoist. Выглядит аккуратно и логично.

✅ DELETE /orders/{orderId}/tasks/{taskId} - удаление задачи из заказа (проекта в Todoist).



Стандартизировались 🙌
Эти посты наглядно показыавают, что при проектировании REST API я не могу работать только с одним методом.
Важно видеть всю систему целиком, все данные.


Остаётся вам передать полные постановки задач на интеграцию 😉

#RestApiGA #ИнтеграцииGA

🔎 Нужно ли уметь проектировать методы REST API системному аналитику? 🔎

REST API — это основной способ интеграции современных систем.

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


Однако некоторым аналитикам требуется не только умение читать чужую документацию, но и способность проектировать методы REST API с нуля.
Это включает как минимум:
✔️ выбор подходящих HTTP-методов (POST, GET, PUT, PATCH, DELETE),
✔️ определение URL,
✔️ и самостоятельное описание JSON-ов.


Что конкретно нужно знать по части REST API системному аналитику зависит от нескольких факторов:

👉 1. Грейд (уровень специалиста)
Все системные аналитики, включая начинающих (junior), должны уметь читать REST API-документацию.
Это включает:
+ Знание назначения методов POST, GET, PUT и других.
+ Понимание структуры URL и способность определить назначение метода, даже без пояснений на естественном языке.
+ Умение читать и описывать JSON, а также формулировать требования к его содержимому
На многих собеседованиях сейчас просят хотя бы на базовом уровне описать метод REST API с нуля. Даже junior-ов.


👉 2. Проект
Бывают простые проекты, бывают сложные. Бывают с REST API или без него (но это редкость).

👉 👉 2.1. В веб-разработке встречаются проекты без API, где UI и серверная логика объединены в одной кодовой базе. Обычно это внутренние системы.
Еще желательно, чтобы проект был без внешних интеграций.
В таком случае с REST API вы не встретитесь.
Такие проекты подходят для начального уровня, но редко интересны опытным аналитикам.

👉 👉 2.2. Если вы работаете над интеграциями с внешними системами, необходимо уметь читать REST API. Умение проектировать методы с нуля не всегда требуется.

👉 👉 2.3. Если ваша система должна предоставлять API для внешних систем, от системного аналитика ожидается умение собирать требования и проектировать методы REST API, т.е. составлять контракты: определять HTTP-метод, URL, JSON-ы и другие параметры.


👉 3. Команда и правила компании
В разных компаниях обязанности по проектированию REST API распределены по-разному.
В одних это зона ответственности разработчиков, в других — системных аналитиков. В любом случае, итоговое решение всегда принимает Backend-разработчик, который может скорректировать предложения аналитика.
Во многих компаниях есть выделенные Backend-команды. В них требуют, чтобы системные аналитики сосредотачивались исключительно на проектировании REST API, и нет задач на работу с пользовательским интерфейсом (UI).


--------
Итого…

Требования к умению проектировать REST API для системного аналитика зависят от уровня специалиста, специфики проекта и подхода компании.

На начальных этапах карьеры достаточно базовых знаний:
+ понимать структуру документации,
+ различать HTTP-методы,
+ и уметь читать JSON.

Однако с ростом квалификации и участием в более сложных проектах навыки проектирования REST API методов с нуля становятся необходимыми. Вмесе с этим просят умение работать с Postman и/или Swagger (знание OpenAPI).

REST API — это уже не просто дополнительный навык, а одна из основных компетенций системного аналитика.

#RestApiGA #ИнтеграцииGA