❌ Работа над ошибками в 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

🙅‍♀️❌ Шаблонные поздравления с Новым годом ❌🙅‍♀️
📚✅ Полезный пост с книгами ✅📚

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

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

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

«То, как мы работаем, – не работает», Тони Шварц
Эта книга-мотиватор, которая помогает работать не много и упорно, а эффективно. Если вы встретились с выгоранием, часто перерабатываете и ничего не успеваете, то книга поможет перестроить ваши рабочие процессы и график. Уже почти 5 лет пользуюсь приёмами из неё.

«Ставка на себя. Как увидеть возможности, не упустить их и построить карьеру мечты», Энн Хайетт
Если вы понимаете, что засиделись на одном месте и боитесь что-то менять из-за неуверенности в своих силах, почитайте вдохновляющую историю Энн, которая начинала свою работу ассистентом в стартапе и младшим помощником руководителя, а по итогам работала рука об руку с основателями мировых IT-компаний как Google.

«Договориться можно обо всем! Как добиваться максимума в любых переговорах», Гэвин Кеннеди
Подойти к руководителю и попросить о повышении ЗП похоже на ночной кошмар, завершающийся отказом? Выход на собеседования вызывает желание вернуться обратно к работе и заниматься привычными задачами. Везде видятся сплошные отказы? Нормально, проходили. Читаем книгу и движемся вперёд.

«Магия утра», Хэл Элрод
Системность. Дисциплина и самоорганизация. Лишние часы в сутках. Эти три предложения отлично харакртеризуют мои результаты по итогам прочтения этой книги.


Желаю вдохновения, уверенности в своих силах и смелых шагов в 2025 году!

Пусть он станет временем, когда сбываются мечты!

Загадывай желания под бой курантов.
Пиши цели.
Я буду с тобой!

Всё получится! 🪄

С наилучшими пожеланиями,
Екатерина Ананьева
и команда GetAnalyst!

📚 Подборка полезных материалов по Интеграциям от GetAnalyst 📚

Для всех, кому хочется продуктивности в большие выходные!

📚 Как аналитику работать с задачами на интеграции — пошаговая инструкция
В этой статье вы найдете пошаговую инструкцию, которая станет помощником при проектировании интеграций для любых систем.

🎧 Postman: навык тестирования REST API за вечер

🎧 Опасные интеграции - про альтернативные сценарии и обработку типовых ошибок

🎧 Подкаст "Проблемы в работе с задачами на интеграции"

🎧 От «умного дома» до «умного города»: новые челленджи IT-аналитиков - интеграции с умными устройствами

🎧 Доставить и не потерять: синхронизация данных в распределенных системах - основы очередей сообщений

🎧 gRPC vs REST API - что выбрать для проекта

📝 Отличия между обычными и интеграционными Use Case

📝 Пример интеграционного Use Case

📝 Инструменты системного аналитика для тестирования в API

📚 Практическое руководство по Postman - тестирование API DaData (с нуля до результатов)

📚 Практическое руководство по Postman - тестирование API ChatGPT

📚 Полный шаблон постановки задачи на интеграционный REST API-метод

🎧 Идемпотентность и коммутативность API: что это и как применяют на практике

🎓 Практический курс Интеграции Систем - работа онлайн с Екатериной Ананьевой и экспертами программы

🎓 Материалы для самообучения по Интеграциям (пакеты вебинаров)


📝 пост в канале
📚 книга, статья или шаблон документации от GetAnalyst
🎧 подкаст или видео


Еще больше материалов по интеграциям от GetAnalyst вы всегда можете найти в канале по хэштегу #ИнтеграцииGA 🙌

Отличного продолжения выходных!