👩‍💻🧑‍💻 Когда Системный Аналитик работает с REST API 👩‍💻🧑‍💻


Когда затрагивают тему REST API, то полезно знать, что могут требовать от Системного Аналитика.

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


👉 При создании новой функциональности
У вас в команде Frontend и Backend разрабатываются отдельно.
Frontend / Мобильные приложения взаимодействуют с Backend по REST API.
Когда в системе нужно добавить новую функциональность, то от аналитика ожидают, что он может

со стороны Backend - спроектировать REST API методы:
▫️ Определить REST API методы, которые нужно разработать для обеспечения работы Frontend.
▫️ Описать алгоритмы их работы, которые будут программировать разработчики.
▫️ Продумать требования к обработке ошибок для этих алгоритмов.
▫️ Сделать ролевую модель доступов к REST API методам.
▫️ Спроектировать структуру API-методов:
+ на естественном языке описать входные параметры запроса и параметры ответа на запрос.
+ продумывать техническую реализацию и описывать сразу тип метода (GET, POST, ...), endpoint (URL), query-параметры, headers запроса и ответа, тело JSON запроса и ответа, статус-код ответа.
▫️ Описывать маппинги (сопоставление) данных между БД и параметрами API-методов (в URL, JSON).
▫️ Формировать техническую API-документацию, которую в дальнейшем будут использовать разработчики: в Postman, Confluence или Swagger (OpenAPI).

со стороны Frontend - подключение разработанного на Backend REST API метода:
▫️ Читать техническую REST API-документацию.
▫️ Проверять работу готовых REST API методов через Postman, чтобы убедиться, что все работает так, как описано в документации.
▫️ Описывать маппинги (сопоставление) данных между UI и параметрами API-методов (в URL, JSON).


👉 Интеграция систем - подключение внешних систем
Состав подзадач аналогичен подключению API на Frontend.
Только работа ведется не с внутренней документацией, а с чужой - на внешние системы.

👉 Интеграция систем - создание интеграционных API-методов
Нужно сделать REST API-метод на Backend, который будет вызывать любой API внешней системы (хоть REST, хоть SOAP, хоть GraphQL).
Состав подзадач аналогичен проектированию API-методов на Backend.
Только маппиг данных теперь будет не только для БД и параметрами нашего API-метода (в URL, JSON). К нему добавятся еще и параметры внешней системы.


👉 Для анализа ошибок работы ПО
Что-то пошло не так при работе Frontend (или мобильного приложения)?
Открываем консоль.
Анализируем запросы и ответы REST API методов.
Тестируем сложные ситуации через Postman, смотрим на результаты и ищем причины ошибок.



Рекомендация:
Для Системного аналитика важно понимать REST API не только с точки зрения возможностей, но и с точки зрения ограничений, типовых проблем и ошибок в проектировании. Чем лучше вы их понимаете, тем качественнее будет работать ПО разработанное по вашим требованиям.


#RestApiGA

💛 Структура методов REST API в одной картинке 💛

Коллеги, публикую для вас картинку-шпаргалку, которую можно использовать при проектировании методов REST API 🙌

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


А чтобы вы наглядно могли сопоставить структуру на картинке с реальными REST API, предлагаю вам посмотреть примеры открытой API-документации для интеграции с крупными сервисами:

ТБанк - Зарплатный проект
API - Умного дома от Яндекс
ЦИАН - Покупка и продажа недвижимости

Проверьте себя!
Это отличная практика по изучению структуры методов REST API.
Сможете ли найти все описанные на картинке параметры в документации?


Дополнительно рекомендую посмотрить эту статью, если вы пропустили пост про связь REST API и протокола HTTP.

#RestApiGA

🐝 Ошибки проектирования методов REST API 🐞

API (программный интерфейс) - это как UI (пользовательский интерфейс).

За нажатием на кнопку “Удалить” может скрываться алгоритм создания 🙈
Да, кнопка называется “Удалить”, но главное то, что запрограммировали разработчики в коде.

Так и с API: за методом POST на создание данных может быть реализован алгоритм получения данных.

Это самое важное, что нужно знать о REST API 🙂


Собрала для вас статью, в которой показала основные ошибки при определении методов REST API - эндпоинтов (метод HTTP + URL):

1. Выбор метода POST, GET, PUT, PATCH, DELETE, который не соответствует действию
2. Все методы POST
3. Глагол действия в URL - названии эндпоинта, который дублирует команду HTTP-метода
4. Опущена важная часть URL
5. Нарушена иерархия в URL
6. Слишком длинный путь в URL
7. Отсутствие элементов пагинации для списка
8. Единственное или множественное число в URL
9. Нарушение корпоративного стиля


Подробности с примерами в статье. Загружаем, изучаем, сохраняем в личный архив 🤝

Рекомендации из этой статьи помогут сделать ваш API интуитивно понятным и соответствующим рекомендациям архитектурного стиля REST API.

#RestApiGA #ElibraGA