🟡🟣 Инструменты для работы с API: руководство СА 🟢🟠
Зачем аналитику знать инструменты для тестирования и документирования API?
👉 Интеграции:
СА необходимо убедиться, что API внешней системы будет работать именно так, как описано в документации (если она есть, а если нет - то составить), чтобы затем предоставить информацию разработчикам.
Тестирование API внешних систем в специализированных инструментах помогает выявить проблемы в работе внешних систем на ранних стадиях разработки, несоответствия документации реальности, а также проверить полноту данных и доступность сервисов в целом.
👉 Backend-команды, которым нужно ставить задачи на API:
Нужно уметь самому с нуля проектировать и документировать API, желательно с использованием специализированных инструментов как Postman и Swagger, а не только в Confluence-подобных системах.
Список инструментов, которые помогают системным аналитикам в тестировании и документировании API:
🟠 Postman
🟡 SoapUI
🟣 Insomnia
🟢 Swagger
Подробности в картинках к посту ☝️
+🐶 Bruno - аналог Postman, всё больше завоёвывает сердца аналитиков, его нет в картинках к посту.
👉 Рекомендую поработать со всеми инструментами и выбрать наиболее удобный для себя.
Делюсь практическими гайдами, с которыми вы сможете поработать с инструментами сами, с понятными пошаговыми инструкциями:
🟠 Postman: Практическое руководство с примером тестирования открытого API
🟠 GraphQL — знакомство на практике через Postman [пошаговая инструкция]
🟠 Postman: навык тестирования REST API за вечер
🟢 Swagger - практическое руководство по документированию API
#RestApiGA
Зачем аналитику знать инструменты для тестирования и документирования API?
👉 Интеграции:
СА необходимо убедиться, что API внешней системы будет работать именно так, как описано в документации (если она есть, а если нет - то составить), чтобы затем предоставить информацию разработчикам.
Тестирование API внешних систем в специализированных инструментах помогает выявить проблемы в работе внешних систем на ранних стадиях разработки, несоответствия документации реальности, а также проверить полноту данных и доступность сервисов в целом.
👉 Backend-команды, которым нужно ставить задачи на API:
Нужно уметь самому с нуля проектировать и документировать API, желательно с использованием специализированных инструментов как Postman и Swagger, а не только в Confluence-подобных системах.
Список инструментов, которые помогают системным аналитикам в тестировании и документировании API:
🟠 Postman
🟡 SoapUI
🟣 Insomnia
🟢 Swagger
Подробности в картинках к посту ☝️
+
👉 Рекомендую поработать со всеми инструментами и выбрать наиболее удобный для себя.
Делюсь практическими гайдами, с которыми вы сможете поработать с инструментами сами, с понятными пошаговыми инструкциями:
🟠 Postman: Практическое руководство с примером тестирования открытого API
🟠 GraphQL — знакомство на практике через Postman [пошаговая инструкция]
🟠 Postman: навык тестирования REST API за вечер
🟢 Swagger - практическое руководство по документированию API
#RestApiGA
Please open Telegram to view this post
VIEW IN TELEGRAM
Please open Telegram to view this post
VIEW IN TELEGRAM
❤27👍6🔥3
Кроме REST API, полезно иметь представление и о SOAP API + его протоколах.
Несмотря на то, что это устаревающий способ интеграции, он всё ещё остаётся популярным в банках, корпоративных системах. Там, где важна структура данных и высокие требования к безопасности.
Ключевые вопросы:
1️⃣ Что такое SOAP?
SOAP (Simple Object Access Protocol) — это протокол прикладного уровня для обмена сообщениями между системами.
👉 Сообщение — это XML-конверт со строгой структурой:
▫️ <Envelope> — общий конверт,
▫️ <Header> — метаданные (безопасность, маршрутизация и т.п.),
▫️ <Body> — данные запроса/ответа,
▫️ <Fault> — описание ошибки.
Ключевые идеи:
✔️ Строгий контракт и валидация по схемам (XSD).
✔️ SOAP не задаёт, как устроен ваш сервис и его бизнес-логика, он лишь стандартизирует формат и способ передачи сообщений между системами.
2️⃣ Что такое SOAP API?
SOAP API — интерфейс, где все операции описаны контрактом WSDL (Web Services Description Language).
👉 WSDL 1.1 содержит:
▫️ types — XSD-схемы данных (общие типы).
▫️ message — абстрактные сообщения (вход/выход операций).
▫️ portType — абстрактный интерфейс: набор операций с их входами, выходами, обработкой ошибок.
▫️ binding — привязка portType к конкретному протоколу и формату (напр., SOAP 1.1/1.2 over HTTP)
▫️ service/port — сервис и его эндпоинты (адреса/URL) для вызова операций.
Плюс экосистема стандартов WS-* (WS-Security, WS-Addressing, WS-ReliableMessaging и др.) для безопасности, маршрутизации, гарантии доставки, транзакций.
P.S. в WSDL 2.0 термины немного другие — interface вместо portType, endpoint вместо port, и там нет message.
3️⃣ На каком протоколе работает SOAP API?
👉 HTTP — протокол прикладного уровня.
• В модели OSI — уровень 7 (Application Layer).
• В TCP/IP — тоже относится к Application.
👉 SOAP — протокол прикладного уровня, аналогично HTTP, но....
SOAP — это протокол обмена сообщениями (XML-конверт), который работает поверх транспорта — чаще HTTP/HTTPS, но может идти и по SMTP, JMS, TCP.
❗️ Сам SOAP определяет формат и правила сообщений, но не транспорт.
4️⃣ Тестирование SOAP API
🟡 SoapUI
🟠 Postman
🟣 Insomnia
и другие инструменты.
5️⃣ SOAP и REST — в чём разница?
👉 SOAP — протокол обмена сообщениями с контрактом WSDL и XML-валидацией (XSD).
👉 REST — архитектурный стиль проектирования веб-API: ресурсы по URL + стандартные HTTP-методы (GET/POST/PUT/PATCH/DELETE), чаще JSON, коды статуса HTTP, кеширование и пр.
Но при этом оба могут использовать HTTP в качестве транспорта.
6️⃣ Когда лучше SOAP, а когда REST?
SOAP, если:
✅ Нужен строгий контракт, типизация и валидация по XSD «из коробки».
✅ Требуются enterprise-требования из WS-*: подписи/шифрование (WS-Security), надежная доставка/идемпотентность, транзакции.
✅ Формат XML и согласованные схемы данных XSD — обязательное требование.
❌ Не используйте, если API планируют вызывать мобильные и веб приложения, он лучше для сервер-сервер интеграций.
REST, если:
✅ Веб/мобильная разработка, взаимодействие микросервисов.
✅ Нужна простота, скорость разработки, удобство фронтов (JSON), кеширование и стандарты HTTP.
✅ Нет строгих требований к WS-расширениям; безопасность решается за счёт OAuth2/JWT/TLS.
Это главные вопросы, которые надо понимать для работы, и которые обычно спрашивают по SOAP.
Сохраняйте в избранное
#ИнтеграцииGA #АрхитектураGA
Please open Telegram to view this post
VIEW IN TELEGRAM
❤27👍5🔥3❤🔥1🥰1
Всё_про_JSON_практическое_руководство_GetAnalyst.png
1 MB
💥 Всё про JSON в одной картинке 💥
JSON - основной формат сообщений, который используется для обмена данными в разработке ПО:
✔️ REST API (запросы и ответы)
✔️ GraphQL (ответы)
✔️ Сообщения для брокеров Kafka / RabbitMQ
✔️ и в других случаях.
Инструменты, которые помогут в работе и на собеседованиях, когда вас спрашивают о JSON:
🔗 jsoneditoronline
🔗 postman
🔗 chatgpt / deepseek / gemini и другие нейросети
А всё остальное, включая подробный разбор структуры JSON, типичные ошибки и рекомендации по проектированию, собрала для вас в практическом руководстве, прикрепленном к посту📚
#RestApiGA
JSON - основной формат сообщений, который используется для обмена данными в разработке ПО:
✔️ REST API (запросы и ответы)
✔️ GraphQL (ответы)
✔️ Сообщения для брокеров Kafka / RabbitMQ
✔️ и в других случаях.
Инструменты, которые помогут в работе и на собеседованиях, когда вас спрашивают о JSON:
А всё остальное, включая подробный разбор структуры JSON, типичные ошибки и рекомендации по проектированию, собрала для вас в практическом руководстве, прикрепленном к посту📚
#RestApiGA
Please open Telegram to view this post
VIEW IN TELEGRAM
🔥28👍8❤🔥4❤1
REST API — один из главных навыков системного аналитика. Его спрашивают на собеседованиях и используют каждый день в задачах бэкенда, микросервисов, интеграций и мобильных приложений.
👉 Приглашаем вас на бесплатный онлайн-практикум, чтобы разобраться с темой и освоить три инструмента, которые реально ускоряют работу аналитика и дают лучшее понимание REST API:
💥 Postman, Insomnia и AI — на практике:
проверим чужие API и спроектируем свои REST API-методы с нуля
🟢 Онлайн
План:
1. Теория по REST API - только то, что пригодится в практике.
2. Postman & Insomnia: создаём коллекции и проверяем внешние API.
3. Настройка AI-ассистента для работы с проектированием REST API.
4. Проектирование и документация собственного REST API-метода в Insomnia + AI.
Это полноценное обучение, которое даст вам реальный опыт работы с REST API и тремя самыми актуальными инструментами 🚀
--------
Занятие проводится в качестве вводного урока к практической программе Дизайн REST API.
--------
Регистрируйтесь и подключайтесь онлайн в следующий четверг! 😉
Please open Telegram to view this post
VIEW IN TELEGRAM
❤14🔥7🎉1
🥳 Осенние офферы + обстановка на рынке найма аналитиков 👩💻
Хочу начать этот пост с благодарности!
Спасибо студентам GetAnalyst, что вы сами пишете про свои офферы, делитесь, что спрашивали на собеседованиях и что помогло ❤️🔥 Это бесценно!
За последний месяц пришло несколько сообщений с офферами, что очень радует!
Продолжайте делиться - ваш опыт помогает сообществу 💙
На скринах:
🇪🇺 трудоустройство в другой стране (не РФ)
🔁 переход из тестирования в системный анализ
💸 ×2 рост в ЗП и куча бонусов
Это сильные кейсы. Они показывают, что всё реально и возможно, даже если не с первого раза 🙌
Что спрашивают по всем грейдам:
✅ Задание на SQL - уже много лет в 9 из 10 случаев
✅ Проектирование БД - логический уровень минимум
✅ REST API - умение проектировать методы (у опытных аналитиков задачи с кучей подвохов)
✅ Интеграции и брокеры (Kafka/RabbitMQ) всё чаще всплывают даже у мидлов
✅ НФТ
✅ Архитектура тоже начала появляться всё чаще и чаще из-за распространения микросервисной архитектуры
✅ Начинают появляться требования по NoSQL
Обстановка на рынке:
▫️ Осень обычно не самая активная на найм, но офферы есть, как мы видим!
▫️ Рынок по-прежнему на стороне работодателя: требования высокие, конкуренция ощутимая.
▫️ Но это не барьер, если у вас есть хорошо оформленное резюме, портфолио и хорошая практическая подготовка, что задачи с собеседований решаются легко.
Личное наблюдение:
Я вижу, как сильно вам помогает детальная обратная связь. Да, это требует времени, но именно она передаёт «реальный» опыт и помогает разобраться.
И именно это подчеркивают наши аналитики, как в процессе, так и после обучения ♥️
👉 Смена работы и собеседования - это тоже как работа. И путь к результату всегда проходит через несколько попыток, в том числе неудачных.
Но всё возможно, если у вас есть цель!
Желаю каждому из вас получить сообщение с оффером мечты или рост внутри компании 😉
А мы рядом, чтобы помочь на этом пути ❤️🔥
#студентыGetAnalyst
Хочу начать этот пост с благодарности!
Спасибо студентам GetAnalyst, что вы сами пишете про свои офферы, делитесь, что спрашивали на собеседованиях и что помогло ❤️🔥 Это бесценно!
За последний месяц пришло несколько сообщений с офферами, что очень радует!
Продолжайте делиться - ваш опыт помогает сообществу 💙
На скринах:
🇪🇺 трудоустройство в другой стране (не РФ)
🔁 переход из тестирования в системный анализ
💸 ×2 рост в ЗП и куча бонусов
Это сильные кейсы. Они показывают, что всё реально и возможно, даже если не с первого раза 🙌
Что спрашивают по всем грейдам:
✅ Задание на SQL - уже много лет в 9 из 10 случаев
✅ Проектирование БД - логический уровень минимум
✅ REST API - умение проектировать методы (у опытных аналитиков задачи с кучей подвохов)
✅ Интеграции и брокеры (Kafka/RabbitMQ) всё чаще всплывают даже у мидлов
✅ НФТ
✅ Архитектура тоже начала появляться всё чаще и чаще из-за распространения микросервисной архитектуры
✅ Начинают появляться требования по NoSQL
Обстановка на рынке:
▫️ Осень обычно не самая активная на найм, но офферы есть, как мы видим!
▫️ Рынок по-прежнему на стороне работодателя: требования высокие, конкуренция ощутимая.
▫️ Но это не барьер, если у вас есть хорошо оформленное резюме, портфолио и хорошая практическая подготовка, что задачи с собеседований решаются легко.
Личное наблюдение:
Я вижу, как сильно вам помогает детальная обратная связь. Да, это требует времени, но именно она передаёт «реальный» опыт и помогает разобраться.
И именно это подчеркивают наши аналитики, как в процессе, так и после обучения ♥️
👉 Смена работы и собеседования - это тоже как работа. И путь к результату всегда проходит через несколько попыток, в том числе неудачных.
Но всё возможно, если у вас есть цель!
Желаю каждому из вас получить сообщение с оффером мечты или рост внутри компании 😉
А мы рядом, чтобы помочь на этом пути ❤️🔥
#студентыGetAnalyst
❤47🔥3❤🔥1🎉1👌1
💾 КЭШ — что важно знать системным аналитикам 💾
Кэш (cache) — быстрый временный слой хранения результатов вычислений или запросов API (и не только), чтобы при повторном обращении к серверу вернуть ответ не выполняя вычисления и логику запроса заново.
👉 Что хранит:
Уже вычисленные данные и/или их части:
JSON ответа, HTML-код, агрегаты, объекты
👉 Что кэшировать:
▫️Карточки сущностей, справочники - медленно меняющиеся сущности
▫️Списки с параметрами фильтров/пагинации
▫️Агрегаты/отчёты: дорогие запросы
▫️HTTP-404 на короткое время
👉 НЕ кэшировать:
▫️Ответы на изменяющие методы (POST/PUT/PATCH/DELETE)
▫️Секретные/чувствительные данные (no-store)
👉 Где хранится:
Для Frontend:
+ в памяти мобилок или десктопов
+ в памяти браузера
+ иногда в локальных БД
Для Backend:
+ CDN/прокси
+ Специализированные СУБД: Redis / Memcached
+ иногда в самой БД - готовые JSON, чтобы не вычислять
👉 Как искать нужные данные:
По ключу кэша - обычно это хеш нормализованного запроса/параметров
👉 Поведение алгоритмов при работе с кэшем:
✅ Cache Hit:
Если данные по ключу кэша найдены, то вернуть их.
Проверить время жизни кэша, прежде чем возвращать ответ
❌ Cache Miss:
Если кэш не найден или данные в кэше устаревшие, то приложение:
+ должно обратиться к источнику за данными (БД или вн. система)
+ формирует ответ (JSON или др)
+ пишет актуальные данные в кэш
🔖 Общий порядок работы на картинках к посту
👉 Политики вытеснения кэша (автоочистка)
▫️ LRU (Least Recently Used) — удаляем те ключи, к которым давно не обращались
▫️ LFU (Least Frequently Used) — удаляем ключи с наименьшим числом обращений
▫️ TTL (Time To Live) — запись жива фиксированное время, потом протухает
▫️ Size-based — выселение по суммарному объёму (байты), часто вместе с LRU/LFU
👉 Заголовки в REST API (Headers)
В запросах:
Cache-Control
If-None-Match
If-Modified-Since
If-Match
If-Unmodified-Since
Only-If-Cached
Pragma (устар.)
В ответах:
Cache-Control
ETag
Last-Modified
Vary
Expires
Age
Date
Cache-Status
Surrogate-Control
#RestApiGA #АрхитектураGA
Кэш (cache) — быстрый временный слой хранения результатов вычислений или запросов API (и не только), чтобы при повторном обращении к серверу вернуть ответ не выполняя вычисления и логику запроса заново.
👉 Что хранит:
Уже вычисленные данные и/или их части:
JSON ответа, HTML-код, агрегаты, объекты
👉 Что кэшировать:
▫️Карточки сущностей, справочники - медленно меняющиеся сущности
▫️Списки с параметрами фильтров/пагинации
▫️Агрегаты/отчёты: дорогие запросы
▫️HTTP-404 на короткое время
👉 НЕ кэшировать:
▫️Ответы на изменяющие методы (POST/PUT/PATCH/DELETE)
▫️Секретные/чувствительные данные (no-store)
👉 Где хранится:
Для Frontend:
+ в памяти мобилок или десктопов
+ в памяти браузера
+ иногда в локальных БД
Для Backend:
+ CDN/прокси
+ Специализированные СУБД: Redis / Memcached
+ иногда в самой БД - готовые JSON, чтобы не вычислять
👉 Как искать нужные данные:
По ключу кэша - обычно это хеш нормализованного запроса/параметров
👉 Поведение алгоритмов при работе с кэшем:
✅ Cache Hit:
Если данные по ключу кэша найдены, то вернуть их.
Проверить время жизни кэша, прежде чем возвращать ответ
❌ Cache Miss:
Если кэш не найден или данные в кэше устаревшие, то приложение:
+ должно обратиться к источнику за данными (БД или вн. система)
+ формирует ответ (JSON или др)
+ пишет актуальные данные в кэш
🔖 Общий порядок работы на картинках к посту
👉 Политики вытеснения кэша (автоочистка)
▫️ LRU (Least Recently Used) — удаляем те ключи, к которым давно не обращались
▫️ LFU (Least Frequently Used) — удаляем ключи с наименьшим числом обращений
▫️ TTL (Time To Live) — запись жива фиксированное время, потом протухает
▫️ Size-based — выселение по суммарному объёму (байты), часто вместе с LRU/LFU
👉 Заголовки в REST API (Headers)
В запросах:
Cache-Control
If-None-Match
If-Modified-Since
If-Match
If-Unmodified-Since
Only-If-Cached
Pragma (устар.)
В ответах:
Cache-Control
ETag
Last-Modified
Vary
Expires
Age
Date
Cache-Status
Surrogate-Control
#RestApiGA #АрхитектураGA
🔥34❤12👍4🥰2
GetAnalyst - REST API - Кэширование.png
7.1 MB
Чтобы управлять кэшированием в REST API, необходимо использовать специальные HTTP-заголовки (headers).
Именно эти технические параметры говорят браузеру, CDN и прокси:
• можно ли отдавать кэшированную копию,
• нужно ли проверять свежесть у origin (вашего сервера/приложения),
• сохранять ли ответ в кэше и на сколько.
Системному аналитику, при постановке задачи на разработчиков, нужно учесть необходимые headers в дизайне (контракте) REST API метода и описать их поведение в алгоритме его работы.
Request headers - Заголовки запросов:
🔑 Cache-Control
🔑 Pragma
If-None-Match
If-Modified-Since
If-Match
If-Unmodified-Since
If-Range
Response headers - Заголовки ответов:
🔑 Cache-Control
🔑 Expires
🔑 ETag
🔑 Last-Modified
🔑 Vary
🔑 Age
🔑 Date
🔑 Cache-Status
Content-Location
Warning
Surrogate-Control
Surrogate-Key
X-Cache / CF-Cache-Status / X-Served-By
Ключами 🔑 отмечены те, которые желательно знать и помнить.
Остальные - всегда можно подсмотреть при необходимости.
👉 Детали по каждому header, пояснения и примеры собраны в гайде - на картинке к посту.
P.S. Вопросы про кэширование в API в последнее время стали чаще задавать на собеседованиях для senior-аналитиков на проекты с высоконагружеными системами
#RestApiGA
Please open Telegram to view this post
VIEW IN TELEGRAM
❤🔥16🔥8❤2👍2😍1
💥 REST API для СА и БА: последний день лучших цен с модулем по БД+SQL в подарок 🔔
Хотим напомнить о завершении предзаписи на практическую программу:
✅ Дизайн REST API
🗓 Старт: 5 ноября 2025
🎁 По заявкам до 28 октября: сниженная цена + дополнительное обучение по БД+SQL в подарок.
Следующий онлайн-поток - Апрель 2026.
С 2026 года будет повышение цен.
👉 Узнать подробности и записаться
⬇️ Кому актуально
Бизнес- и системным аналитикам, которым нужно уверенно проектировать REST API, общаться с бэкенд-разработчиками «на одном языке», разбираться в смежных подходах к проктированию (gRPC, GraphQL) и спокойно проходить собеседования по теме API.
⬇️ Что получите к финалу
За 10 недель вы создадите готовый портфолио-проект:
▫️ постановки задач на REST API методы в Confluence,
▫️ корпоративный стандарт по дизайну REST API-методов,
▫️ Postman-коллекции по своему и чужим API,
▫️ API-спецификация в OpenAPI (Swagger),
▫️ mock-сервер с рабочим API на заглушках.
+ комплект шаблонов и примеров ТЗ для аналитика.
Формат обучения ⬇️
✅ 8 онлайн-встреч
✅ 9 теоретических модулей в записи
✅ Проверка ДЗ по проекту
✅ 6 месяцев доступа к материалам
----------------------------
⬇️ Бесплатный вводный урок
🟠🟣🤖 Postman, Insomnia и AI
🗓 30 октября, в 19:00 Мск (чт)
🔗 Зарегистрироваться на урок
----------------------------
💬 Нужна консультация?
Пишите @getanalyst или на [email protected] - поможем оценить текущие навыки и ответим на все вопросы.
Хотим напомнить о завершении предзаписи на практическую программу:
✅ Дизайн REST API
🎁 По заявкам до 28 октября: сниженная цена + дополнительное обучение по БД+SQL в подарок.
Следующий онлайн-поток - Апрель 2026.
С 2026 года будет повышение цен.
👉 Узнать подробности и записаться
⬇️ Кому актуально
Бизнес- и системным аналитикам, которым нужно уверенно проектировать REST API, общаться с бэкенд-разработчиками «на одном языке», разбираться в смежных подходах к проктированию (gRPC, GraphQL) и спокойно проходить собеседования по теме API.
⬇️ Что получите к финалу
За 10 недель вы создадите готовый портфолио-проект:
▫️ постановки задач на REST API методы в Confluence,
▫️ корпоративный стандарт по дизайну REST API-методов,
▫️ Postman-коллекции по своему и чужим API,
▫️ API-спецификация в OpenAPI (Swagger),
▫️ mock-сервер с рабочим API на заглушках.
+ комплект шаблонов и примеров ТЗ для аналитика.
Формат обучения ⬇️
✅ 8 онлайн-встреч
✅ 9 теоретических модулей в записи
✅ Проверка ДЗ по проекту
✅ 6 месяцев доступа к материалам
----------------------------
⬇️ Бесплатный вводный урок
🟠🟣
----------------------------
Пишите @getanalyst или на [email protected] - поможем оценить текущие навыки и ответим на все вопросы.
Please open Telegram to view this post
VIEW IN TELEGRAM
❤8👍2🔥2
🐞 Знай HTTP-коды и учитывай их в требованиях на REST API🐞
В любой интеграции по API важно не только предусмотреть happy path (успешный путь), но и заранее описать, как система должна вести себя при ошибках.
📌 Что нужно сделать при проектировании ответов на API-запросы
0️⃣ Перечислить успешные ответы
+ 200 OK - Успех
+ 201 Created — Создано (новая запись в БД)
+ 202 Accepted — Принято в обработку (запрос принят, но обработка не завершена, часто используется при асинхронных задачах - отчёты, отправка email и др)
+ 204 No Content — Нет содержимого (запрос выполнен успешно, но в ответе нет тела)
1️⃣ Перечислить типовые ошибки и описать реакцию API на них:
+ 401 Unauthorized — Неверный логин/токен
+ 403 Forbidden — Нет прав
+ 429 Too Many Requests — Превышен лимит запросов
2️⃣ Добавить требования к специфичным ошибкам:
+ 400 Bad Request — Ошибка во входных данных
+ 409 Conflict — Создание дубликатов
+ 500 Internal Server Error — Внутренний сбой в работе сервера
+ и другие.
Все HTTP-статусы тут.
3️⃣ Добавить альтернативные сценарии в Use Case для API-метода, которые ведут к описанным в п.1 и 2 ошибкам.
4️⃣ Сделать JSON-структуру ответов об ошибках единообразной
5️⃣ В OpenAPI спецификации (Swagger) добавить секции:
6️⃣ Отразить примеры ошибок в документации Confluence и всегда иметь соответствующий раздел в шаблоне задачи.
Помните, что ошибки тоже важная часть программного интерфейса - API!
Если все ошибки задокументированны чётко и понятно, пользователи (и разработчики) будут вам благодарны, и вы сможете повысить UX приложений 🙌
🔗 Cтатья про документирование ошибок в REST API
#RestApiGA
В любой интеграции по API важно не только предусмотреть happy path (успешный путь), но и заранее описать, как система должна вести себя при ошибках.
📌 Что нужно сделать при проектировании ответов на API-запросы
0️⃣ Перечислить успешные ответы
+ 200 OK - Успех
+ 201 Created — Создано (новая запись в БД)
+ 202 Accepted — Принято в обработку (запрос принят, но обработка не завершена, часто используется при асинхронных задачах - отчёты, отправка email и др)
+ 204 No Content — Нет содержимого (запрос выполнен успешно, но в ответе нет тела)
1️⃣ Перечислить типовые ошибки и описать реакцию API на них:
+ 401 Unauthorized — Неверный логин/токен
+ 403 Forbidden — Нет прав
+ 429 Too Many Requests — Превышен лимит запросов
2️⃣ Добавить требования к специфичным ошибкам:
+ 400 Bad Request — Ошибка во входных данных
+ 409 Conflict — Создание дубликатов
+ 500 Internal Server Error — Внутренний сбой в работе сервера
+ и другие.
Все HTTP-статусы тут.
3️⃣ Добавить альтернативные сценарии в Use Case для API-метода, которые ведут к описанным в п.1 и 2 ошибкам.
2А. Клиент передал номер телефона в неверном формате.
→ Вернуть ошибку HTTP-400 и сообщение "Неверный формат номера телефона, ожидается 10 цифр"
4️⃣ Сделать JSON-структуру ответов об ошибках единообразной
{
"errorCode": "INVALID_PHONE",
"message": "Текст ошибки"
}
5️⃣ В OpenAPI спецификации (Swagger) добавить секции:
responses:
'400':
description: Неверные параметры запроса
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
6️⃣ Отразить примеры ошибок в документации Confluence и всегда иметь соответствующий раздел в шаблоне задачи.
Помните, что ошибки тоже важная часть программного интерфейса - API!
Если все ошибки задокументированны чётко и понятно, пользователи (и разработчики) будут вам благодарны, и вы сможете повысить UX приложений 🙌
#RestApiGA
Please open Telegram to view this post
VIEW IN TELEGRAM
👍9❤4🔥1
Готовы получать новый уникальный опыт по тестированию и документированию REST API?
Уже завтра ждём вас на бесплатном практическом вебинаре для бизнес- и системных аналитиков:
💥 Postman, Insomnia и AI для REST API
🟢 Прямой эфир
В результате этого обучения:
✅ Получите опыт работы с Postman и Insomnia.
✅ Сделаете коллекции запросов к реальному API для личного портфолио.
✅ Научитесь использовать AI-инструменты (GeminiAI + ChatGPT) на продвинутом уровне для ускорения работы.
✅ Получите примеры постановок задач на REST API-методы.
✅ Спроектируете и задокументируете REST API-метод с нуля через Insomnia.
Будем погружаться в сложную теорию через реальную работу! 🚀
--------
Занятие проводится в качестве вводного урока к практической программе Дизайн REST API.
--------
До встречи в прямом эфире завтра, в 19:00 Мск! ❤️
Please open Telegram to view this post
VIEW IN TELEGRAM
🔥4❤2👌1