Работа с API (практика)

На проекте API — не «техническая деталь бэкенда», а контракт между системами, который вы фиксируете в требованиях, проверяете на стенде и принимаете по критериям. Эта статья закрывает практический минимум системного аналитика: прочитать контракт, выполнить smoke, собрать матрицу сценариев и сформулировать проверяемые AC — без подмены разработчика и без уровня «нарисовали стрелку на диаграмме». Теория HTTP, REST и SOAP — в 07.02 Принципы работы HTTP, REST, SOAP; здесь — один отработанный цикл «OpenAPI → стенд → AC → шаблон спецификации».

1. Суть темы

Практическая работа с API (Application Programming Interface, программный интерфейс приложения) для системного аналитика — цикл «понять контракт → проверить поведение → зафиксировать требования → подтвердить приёмку». Вы работаете с существующим или проектируемым интерфейсом как с проверяемым артефактом: каждый endpoint, схема данных и код ответа должны быть трассируемы к бизнес-сценарию.

Граница темы:

Ваша задача — не написать клиент, а верифицировать интерфейс: сверить документацию с фактическим поведением на стенде, выявить пробелы в контракте и перевести их в требования с воспроизводимыми примерами. Вы фиксируете наблюдаемое поведение и AC; проектирование политик (OAuth flow, IP allowlist, breaking changes) — в соседних заметках по ссылкам. Это часть 02.04.01 Верификация и валидация (V&V) на уровне интеграции.

flowchart LR
    A[Бизнес-сценарий] --> B[Контракт API / OpenAPI]
    B --> C[Тестовый вызов на стенде]
    C --> D[Спецификация и критерии приёмки]
    D --> E[Приёмка интеграции]
    C -.->|расхождение| B

2. Ключевые понятия

После этого раздела вы должны уметь руками: прочитать одну операцию в OpenAPI до конкретного requestBody/responses (включая $ref в components/schemas), выполнить smoke через curl или Postman и перевести матрицу «сценарий → код → тело» в AC. Сквозной пример на POST /orders — в §3; здесь — опорные определения.

Контракт и спецификация

Контракт API — согласованное описание ресурсов, операций, параметров, схем данных, кодов ответа и ошибок. Для REST de facto стандарт — OpenAPI (YAML или JSON); детали нотаций — в 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf).

Endpoint — единица проверки: URL + HTTP-метод + ожидаемые заголовки и тело. В Postman или curl вы сохраняете endpoint как воспроизводимый запрос с параметрами окружения (dev, stage, prod).

Минимальный набор полей OpenAPI, которые аналитик читает до конкретной схемы:

Как читать $ref: в requestBody часто стоит { "$ref": "#/components/schemas/OrderCreate" } — переходите в components/schemas/OrderCreate и там ищите required, properties, ограничения. В allOf несколько схем склеиваются: базовый тип + расширение — проверяйте все части. Swagger UI и Redoc разворачивают ссылки автоматически; в сыром YAML без этого навыка легко пропустить обязательное поле.

Swagger UI и Redoc позволяют просматривать спецификацию и выполнять «Try it out» на стенде; Prism и OpenAPI Generator генерируют mock-сервер по контракту до готовности backend. Ошибка в UI ≠ дефект API — см. §3 («CORS и Swagger UI»).

Запрос, ответ и коды статуса

HTTP-запрос (request) состоит из метода, URL, query-параметров, заголовков (headers) и тела (body). Ответ (response) — статус-код, заголовки и тело.

На практике вы фиксируете матрицу «сценарий → код → тело ошибки». Сверяйте коды с контрактом, а не с «идеальным REST из учебника»: многие API отдают семантические ошибки как 400, а не 422 — это не дефект, если так описано в спецификации.

401 vs 403: 401 = «кто вы?» (аутентификация не пройдена); 403 = «мы знаем кто вы, но операция недоступна» (авторизация).

Тело ошибки сверяйте со схемой в контракте: поля code, message, field или Problem Details (RFC 9457, application/problem+json). Пример AC для трассировки: «При 400 на POST /orders тело ошибки содержит correlationId, совпадающий с X-Request-Id запроса». Детали форматов — 07.03 Основы XML, JSON, YAML.

Аутентификация и авторизация

Authentication (аутентификация) — доказательство личности клиента; authorization (авторизация) — проверка права на операцию. На стенде проверяйте три состояния: без токена, с невалидным токеном, с недостаточным scope.

Типовые схемы — что зафиксировать как наблюдаемое поведение (проектирование политик — 03.05.05 Безопасность API):

Идемпотентность, пагинация, версионирование

Различайте два уровня — путаница даёт неверные AC на платежах и заказах:

Если Idempotency-Key (или аналог) обязателен по бизнес-логике, но отсутствует в OpenAPI (parameters, headers, описание операции) — это пробел контракта: оформите как требование или defect, а не как «неформальный заголовок для Postman». Без записи в контракте AC и handoff QA остаются неформальными.

Pagination (пагинация) — стиль влияет на AC списков; проверьте граничные случаи (пустой список, max limit, терминальная страница cursor/link headers).

Versioning (версионирование) — на стенде определите, какую версию вызываете (path, header, deploy tag). info.version — версия документа, не всегда runtime. Политики breaking changes — 03.05.07 Управление версионированием API и жизненным циклом.

Rate limiting — негативный smoke: превышение квоты → 429 и Retry-After; для воспроизведения нужен test quota. Формулировка NFR — 03.06.03 Rate Limiting — управление пропускной способностью.

Mock, contract testing, webhook

Mock / stub — имитация API до готовности backend (Postman Mock, WireMock, Prism).

Contract testing (контрактное тестирование): lint OpenAPI (Spectral), consumer-driven contracts (Pact), gate в CI — 07.06 CICD и конвейеры — влияние на требования, 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf). Для контрактов gRPC/GraphQL — также 03.05.04 Контрактное программирование и протоколы (gRPC, GraphQL). Ваша зона — требование к gate, не настройка pipeline: «OpenAPI проходит lint до merge»; «ответ на стенде валидируется по JSON Schema из контракта».

Webhook / callback — исходящий HTTP-вызов от системы к подписчику; контракт — AsyncAPI — 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf), 03.05.04 Асинхронное взаимодействие (очереди, Kafka, Events). Пять шагов приёмки — в §3.

REST, SOAP, gRPC, GraphQL — минимум на стенде

REST разобран в сквозном примере §3. Для остальных стилей — воспроизводимый минимум:

SOAP — WSDL + SoapUI или curl с envelope; шаблон AC — 10.01.05 Шаблон спецификации SOAP API:

curl -X POST 'https://{host}/soap/OrderService' \
  -H 'Content-Type: text/xml; charset=utf-8' \
  -H 'SOAPAction: CreateOrder' \
  -d @create-order-envelope.xml

gRPC — .proto из Git, artifact registry или у owner сервиса; вызов через grpcurl — 03.05.02 Синхронные протоколы (REST, gRPC, GraphQL):

# -import-path и -proto — путь к артефакту контракта на stage
grpcurl -plaintext \
  -import-path ./proto -proto order/v1/order.proto \
  -d '{"product_id":"SKU-42","quantity":1}' \
  {host}:50051 order.v1.OrderService/CreateOrder

GraphQL — Playground/Altair; если introspection отключён на stage, schema только из SDL-артефакта в репозитории:

curl -X POST 'https://{host}/graphql' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"query":"mutation { createOrder(input: {productId: \"SKU-42\", quantity: 1}) { id } }"}'

Multipart и бинарные вложения: Content-Type: multipart/form-data, лимит размера — 07.03 Основы XML, JSON, YAML.

Инструменты практического минимума

Минимальный набор артефактов: OpenAPI с info.version; environment без секретов (утечки при export — 08.07 Основы кибербезопасности для системного аналитика); пример запроса/ответа с correlation id (X-Request-Id, traceparent).

3. Как применяется в работе аналитика

Сквозной пример: POST /orders от OpenAPI до AC

Один критичный поток, через который проходят auth, идемпотентность, негативы и перенос в шаблон. Остальные разделы §3 дополняют этот каркас, а не дублируют его.

Шаг 1. Прочитать операцию в OpenAPI

• paths./v1/orders.post: requestBody → $ref → components/schemas/OrderCreate (productId, quantity в required).
• responses: 201, 400, 401, 403, 409; схемы ошибок в components/schemas/Error.
• security: Bearer JWT; параметр Idempotency-Key в header — если отсутствует, заводите defect на контракт (см. §2).
• servers: stage URL; версия API — /v1/ в path.

Шаг 2. Матрица сценариев

Шаг 3. Smoke на стенде

Предусловия: Bearer token со scope orders:write; OAuth refresh, если сессия длиннее TTL; seed SKU-42.

curl -X POST 'https://{host}/v1/orders' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: test-order-001' \
  -H 'X-Request-Id: trace-smoke-001' \
  -d '{"productId": "SKU-42", "quantity": 1}'

Сверьте статус, required-поля по JSON Schema (через $ref) и correlation id в ответе/ошибке.

Шаг 4. Три AC из матрицы

• «При POST /orders с валидным телом возвращается 201 и orderId в теле ответа».
• «При отсутствии scope orders:write возвращается 403 с телом ошибки по согласованной схеме».
• «Повторный запрос с тем же Idempotency-Key после timeout возвращает 200/201 с тем же orderId».

Шаг 5. Перенос в 10.01.04 Шаблон спецификации REST API

После smoke заполните в шаблоне: operation id и path; request/response schemas с examples со стенда; матрицу error codes; securitySchemes; NFR-пункты (timeout, idempotency header, correlation). Коллекция Postman — производный артефакт для прогона, не точка истины.

Разбор документации

Получите OpenAPI, WSDL, Postman Collection или страницу в Confluence — 02.05.06 Инструменты управления требованиями (Jama, DOORS, Confluence). Выделите акторов и границу системы — 03.01.02 Моделирование контекста системы (Context Diagram); критические операции свяжите с потоками — 03.01.04 Интерфейсы и интеграционные взаимодействия. Сопоставьте строки матрицы с user story — 02.03.04 Трассировка требований (концепция), 04.02 Пользовательские истории (User Stories) и Job Stories.

Если спецификации нет — целевое состояние contract-first и 10.01.04 Шаблон спецификации REST API. Reverse engineering (HAR, логи gateway) — временный черновик:

1. Экспорт HAR или лог gateway за типовой сценарий.
2. Список операций: метод, path, query, auth-заголовки.
3. Черновик paths с примерами request/response; пометка draft-reverse-engineered.
4. Согласование с owner контракта и срок замены на утверждённый OpenAPI — 09.06 Ведение переговоров с техническими командами.

Критерий готовности черновика для smoke: заполнены paths всех критичных операций сценария; для каждой — пример request и хотя бы один response (2xx + один 4xx); указаны securitySchemes и servers. Иначе команда продолжает «жить на HAR».

Предусловия smoke

Smoke блокируется доступом, а не API:

1. Учётки: client_id/secret, scope; OAuth token endpoint и refresh; mTLS-сертификат.
2. Seed data: id для позитивных и негативных кейсов.
3. Окружение: dev/stage, VPN, версия API.
4. Очистка: sandbox reset.

Зафиксируйте владельца — 10.04 Чеклист аналитика перед стартом разработки.

Smoke, негативы и граница с QA

Smoke — ранняя V&V интеграции — 02.04.01 Верификация и валидация (V&V), 02.04.03 Управление качеством требований; статический разбор без запуска — 08.03 Тестирование требований (статическое тестирование).

Граница аналитик / QA: вы подтверждаете проверяемость контракта, ключевые сценарии и AC; в handoff — матрица, curl/коллекция, seed. Регресс, нагрузка, pentest, Pact в CI — QA/DevOps.

К сквозному примеру добавьте по контракту:

• optimistic lock (If-Match / ETag → 409);
• 202 + polling: «POST /jobs → 202 и jobId; GET /jobs/{id} → терминальный статус; correlationId совпадает»;
• 202 + webhook: mock-подписчик, AsyncAPI, HMAC; retry без дубликата;
• multipart: файл выше лимита → код и тело по контракту;
• rate limit: test quota → 429 (один раз на проект, не на общем ключе).

Для Kafka/RabbitMQ вместо HTTP callback — 10.01.06 Шаблон спецификации Producer (Kafka, RabbitMQ), 10.01.07 Шаблон спецификации Consumer (Kafka, RabbitMQ).

Каждый сценарий — критерий приёмки (Acceptance Criteria) — 02.04.02 Критерии приёмки (Acceptance Criteria).

Согласование расхождений

Документация ≠ API → defect. Шаблон: endpoint, expected, actual, версия API, окружение, X-Request-Id, curl export. Owner контракта утверждает изменение; OpenAPI в Git — точка истины — 07.05 Системы контроля версий (Git) для документации.

Проверяемые NFR на стенде (не проектирование с нуля)

В 10.01.12 Шаблон нефункциональных требований (NFR) — только наблюдаемое:

• timeout и retry с idempotency;
• correlation headers в ошибках;
• Sunset / Deprecation: GET или OPTIONS к deprecated endpoint → заголовки Deprecation: true, Sunset: <HTTP-date>; AC: «при вызове /v1/orders возвращается Sunset с датой не позже YYYY-MM-DD».

Сверьте поля со 03.03.03 Словарь данных (описание) и 07.01 Базы данных и SQL на уровне аналитика.

Участие в приёмке (UAT интеграции)

Когда «не достучались до стенда»

Проверьте контур: DNS, TLS, VPN — 07.07 Сетевые основы (подсети, протоколы и маршрутизация).

API Gateway vs backend: strip prefix, rewrite path, auth на perimeter — сверьте route table и upstream — 03.01.04 Интерфейсы и интеграционные взаимодействия.

CORS и Swagger UI: «blocked by CORS» на FE — политика origin на gateway, не обязательно дефект backend. Воспроизведите тем же запросом через curl/Postman. Для preflight: OPTIONS с Origin и Access-Control-Request-Method → 204/200 с Access-Control-Allow-*; расхождение OPTIONS vs POST указывает на perimeter. Поведение под нагрузкой — 05.04 DevOps и непрерывная поставка — влияние на требования.

4. Типовые ошибки и ограничения

Ограничения роли аналитика

• Нет полномочий менять production — sandbox, synthetic data.
• PCI и персональные данные — 08.06 Юридические и регуляторные требования РФ (PCI-DSS); токены в коллекциях и export — 08.07 Основы кибербезопасности для системного аналитика.
• Нагрузочное тестирование, pentest, настройка Pact — отдельные роли.

Ошибки при проверке API

Когда практики недостаточно

REST не покрывает pub/sub — 03.05.04 Асинхронное взаимодействие (очереди, Kafka, Events), 03.05.06 Event-Driven Architecture. За одним endpoint — несколько сервисов — 03.01.04 Интерфейсы и интеграционные взаимодействия, 03.02.03 Диаграмма последовательности (Sequence Diagram).

Связи с другими разделами базы

Если задача — …

• Первый smoke REST на новом стенде → 07.02 Принципы работы HTTP, REST, SOAP, эта статья §3 (сквозной пример), 10.01.04 Шаблон спецификации REST API
• Нет OpenAPI, только HAR/логи → §3 reverse engineering, 09.06 Ведение переговоров с техническими командами, 10.01.04 Шаблон спецификации REST API
• SOAP / gRPC / GraphQL → §2 минимум на стенде, 03.05.02 Синхронные протоколы (REST, gRPC, GraphQL), 10.01.05 Шаблон спецификации SOAP API
• Webhook или Kafka → §2–3, 03.05.04 Асинхронное взаимодействие (очереди, Kafka, Events), 10.01.06 Шаблон спецификации Producer (Kafka, RabbitMQ)
• Auth, версии, rate limit — политика, не smoke → 03.05.05 Безопасность API, 03.05.07 Управление версионированием API и жизненным циклом, 03.06.03 Rate Limiting — управление пропускной способностью
• Выбор стиля интеграции → 03.05.01 Виды интеграции (точка-точка, ESB, API-led)
• AC, V&V, трассировка → 02.04.01 Верификация и валидация (V&V), 02.04.02 Критерии приёмки (Acceptance Criteria), 10.01.15 Шаблон матрицы трассировки
• Lint OpenAPI, gate в CI, Pact → 07.06 CICD и конвейеры — влияние на требования, 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf)
• Сеть, gateway, CORS → 07.07 Сетевые основы (подсети, протоколы и маршрутизация), 03.01.04 Интерфейсы и интеграционные взаимодействия
• Секреты, PCI, export коллекций → 08.07 Основы кибербезопасности для системного аналитика, 08.06 Юридические и регуляторные требования РФ (PCI-DSS)
• Документы в Confluence/Jama → 02.05.06 Инструменты управления требованиями (Jama, DOORS, Confluence), 04.01 Форматы документов (Vision&Scope, BRD, SRS, FRD)

Источники и дополнительные материалы

Стандарты и спецификации

• RFC 9110: HTTP Semantics — https://www.rfc-editor.org/rfc/rfc9110.html
• RFC 6749: The OAuth 2.0 Authorization Framework — https://www.rfc-editor.org/rfc/rfc6749.html
• RFC 8594: The Sunset HTTP Header Field — https://www.rfc-editor.org/rfc/rfc8594.html
• RFC 9457: Problem Details for HTTP APIs — https://www.rfc-editor.org/rfc/rfc9457.html
• OpenAPI Specification — https://spec.openapis.org/oas/latest.html
• AsyncAPI Specification — https://www.asyncapi.com/docs/reference/specification/latest
• Understanding JSON Schema — https://json-schema.org/understanding-json-schema/

Справочники и документация

• MDN — Обзор HTTP — https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview
• MDN — HTTP response status codes — https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status
• MDN — REST (глоссарий) — https://developer.mozilla.org/en-US/docs/Glossary/REST
• Swagger Documentation (OpenAPI Guide) — https://swagger.io/docs/specification/about/
• Stoplight — API Design Guide — https://stoplight.io/api-design-guide
• Stoplight — Spectral (OpenAPI lint) — https://stoplight.io/open-source/spectral
• Redoc — документация — https://redocly.com/docs/redoc/

Практические руководства

• curl — manpage — https://curl.se/docs/manpage.html
• Postman Learning Center — https://learning.postman.com/docs/introduction/overview/
• Postman — Authorization — https://learning.postman.com/docs/sending-requests/authorization/authorization/
• SmartBear SoapUI — Getting Started — https://www.soapui.org/docs/getting-started/
• Stoplight — Prism (mock по OpenAPI) — https://stoplight.io/open-source/prism
• grpcurl — https://github.com/fullstorydev/grpcurl