Продолжая использовать сайт, вы даете согласие на обработку файлов cookies. Если вы не хотите, чтобы ваши данные обрабатывались, покиньте сайт
Принять

Документация и проектирование API: полное руководство для системного аналитика

Документация API — одна из важных зон работы системного аналитика в интеграционных проектах. Когда одна система должна получить данные от другой, отправить команду или инициировать действие, команде необходимо точно договориться, как будет происходить это взаимодействие. Какие операции доступны? Какие данные передаются? Что система вернет в ответ? Что произойдет при ошибке? Ответы на эти вопросы появляются в процессе проектирования API и фиксируются в документации.

Для аналитика API — это не только набор endpoints и HTTP-методов. За каждым вызовом стоит бизнес-сценарий: пользователь оформляет заказ, сервис проверяет остатки, платежная система сообщает результат операции, CRM получает данные клиента. Задача аналитика — связать потребность бизнеса с понятным и непротиворечивым контрактом взаимодействия систем.

Разберем REST, SOAP и GraphQL, структуру документации API, основные правила проектирования REST API, инструменты Swagger/OpenAPI, Postman и Redoc, а также посмотрим, зачем системному аналитику понимать тестирование API.

REST, SOAP и GraphQL: какие типы API встречаются аналитику

Способ взаимодействия систем зависит от архитектуры и требований проекта. Системный аналитик может встретить разные подходы: REST, SOAP и GraphQL

REST

REST (Representational State Transfer) — архитектурный стиль построения распределенных систем. В REST API работа обычно организуется вокруг ресурсов, доступных по URI, а действия выполняются с использованием стандартной семантики HTTP.

Например:
GET /orders/125

может использоваться для получения заказа с идентификатором 125.
REST широко применяется в веб- и мобильных приложениях благодаря работе поверх HTTP, понятной модели ресурсов и совместимости с большим количеством инструментов.

При этом REST — не протокол и не конкретный формат данных. Например, JSON часто используется в REST API, но сам архитектурный стиль не требует исключительно JSON.

REST, SOAP и GraphQL: какие типы API встречаются аналитику

Способ взаимодействия систем зависит от архитектуры и требований проекта. Системный аналитик может встретить разные подходы: REST, SOAP и GraphQL.

SOAP

SOAP — протокол обмена структурированными сообщениями. Сообщения SOAP используют XML, а контракт сервиса может описываться с помощью WSDL.

SOAP можно встретить в корпоративных и интеграционных системах, где важны формализованные контракты и используются соответствующие стандарты экосистемы Web Services.

Для аналитика принципиально понимать контракт взаимодействия: какие операции предоставляет сервис, какие сообщения принимает и возвращает, какие ошибки возможны.

GraphQL

GraphQL — язык запросов к API и среда выполнения таких запросов. В отличие от типичного REST-подхода, где сервер определяет структуру ответа конкретного endpoint, в GraphQL клиент может запросить необходимые ему поля в рамках схемы API.

Например, одному экрану приложения могут понадобиться только id, name и price товара, а другому — дополнительно характеристики и изображения. GraphQL позволяет сформировать запрос под конкретную потребность клиента.

Выбор между REST, SOAP и GraphQL нельзя свести к правилу «новое против старого». Он зависит от существующей архитектуры, требований, интеграционного ландшафта и задач проекта.

Документация API: что в ней должно быть

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

Для каждого метода обычно необходимо определить:

  • endpoint;
  • HTTP-метод;
  • назначение операции;
  • параметры пути и запроса;
  • заголовки, если они существенны;
  • тело запроса;
  • обязательность и ограничения полей;
  • структуру успешного ответа;
  • возможные ошибки;
  • примеры запросов и ответов;
  • требования к авторизации или аутентификации, если они применимы.

Конкретный состав документации зависит от API и стандартов проекта. Не каждому методу нужны все перечисленные элементы: например, у GET-запроса может отсутствовать тело запроса.

Пример документации метода GET /users/{id}

Допустим, сервис предоставляет данные пользователя.

Метод:

GET /users/{id}

Назначение: получить данные пользователя по идентификатору.

Path parameter:

id — идентификатор пользователя, обязательный.

Пример запроса:

GET /users/125

Успешный ответ — 200 OK:
{
"id": 125,
"name": "Alex",
"email": "alex@example.com",
"status": "active"
}
Возможный ответ, если пользователь не найден — 404 Not Found:
{
"code": "USER_NOT_FOUND",
"message": "User not found"
}
Уже из такого описания разработчик понимает, куда отправлять запрос и какой результат ожидать, а тестировщик получает основу для позитивного и негативного сценариев.

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

Инструменты документации API: Swagger/OpenAPI, Postman и Redoc

Эти инструменты часто упоминаются рядом, хотя решают разные задачи.
Инструмент
Основная задача
Что удобно аналитику
Важное ограничение
Swagger / OpenAPI
Формальное описание НТТР API
Описывать операции, параметры, схемы данных, ответы и ошибки
Swagger и OpenAPI — не полные синонимы: OpenAPI — спецификация, Swagger — набор инструментов вокруг
Postman
Работа с АРІ-запросами и коллекциями
Отправлять запросы, сохранять примеры, проверять сценарии, организовывать коллекции
Не заменяет само проектирование контракта
Redoc
Представление OpenAPt-описания в виде читаемой документации
Получать удобное для чтения представление API
Качество результата зависит от качества исходного OpenAPI-описания

Swagger и OpenAPI

OpenAPI позволяет описывать HTTP API в машиночитаемом формате JSON или YAML. В спецификации можно определить paths, операции, параметры, request body, схемы данных, ответы и другие составляющие контракта.

Swagger — экосистема инструментов, работающих с OpenAPI. Например, Swagger Editor позволяет редактировать описание, а Swagger UI — отображать его в интерактивном виде.

Фрагмент OpenAPI-описания может выглядеть так:
paths:
/users/{id}:
get:
summary: Получить пользователя
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Пользователь найден
'404':
description: Пользователь не найден
Для системного аналитика ценность такого формата в том, что контракт перестает существовать только в виде текста для человека. Структурированное описание могут использовать различные инструменты разработки, документирования и тестирования.

Postman

Postman позволяет создавать и отправлять HTTP-запросы, работать с параметрами, headers и body, сохранять запросы в коллекции и выполнять проверки ответов. Для аналитика это удобный способ проверить фактическое поведение API.

Например, если документация утверждает, что GET /users/125 возвращает статус 200 и объект пользователя, аналитик может выполнить запрос и сравнить фактический ответ с контрактом.

Postman особенно полезен при разборе существующих интеграций, согласовании примеров и первичной проверке сценариев.

Redoc

Redoc используется для визуального представления API, описанного в OpenAPI. Если OpenAPI-файл содержит десятки методов и схем, читать YAML напрямую неудобно. Redoc превращает спецификацию в структурированную документацию с навигацией по операциям и моделям данных.

Таким образом, OpenAPI задает структуру описания, а инструменты вокруг нее помогают создавать, проверять и отображать документацию.

Проектирование API: от бизнес-задачи к контракту

Проектирование API начинается не с выбора красивого URL. Сначала необходимо понять сценарий взаимодействия. Допустим, интернет-магазину требуется API для работы с заказами.

Сценарии:
  1. получить список заказов;
  2. получить конкретный заказ;
  3. создать заказ;
  4. изменить допустимые данные заказа;
  5. отменить заказ.

После этого аналитик может переходить к структуре ресурсов и операций.

Основные HTTP-методы

Для REST API особенно важна корректная семантика HTTP-методов.

GET используется для получения представления ресурса.

GET /orders/125

POST часто используется для создания нового ресурса или выполнения операции, семантика которой определяется API.

POST /orders

PUT используется для создания или полной замены состояния ресурса по заданному URI в соответствии с контрактом API.

PUT /users/125

PATCH предназначен для частичного изменения ресурса.

PATCH /orders/125

DELETE — для удаления ресурса.

DELETE /users/125

Выбор метода должен отражать смысл операции. Использование POST /getUser только потому, что «POST умеет передавать данные», делает API менее последовательным и хуже использует семантику HTTP.

Проектирование REST API: ресурсы, именование и параметры

Имена ресурсов

В REST API URL лучше строить вокруг ресурсов, а не команд.

Вместо:
/getOrders
логичнее:
GET /orders
Вместо:
/createOrder
— использовать:
POST /orders
Так действие определяется HTTP-методом, а URI обозначает ресурс.

Последовательность важнее попытки найти единственное «идеальное» имя. Если команда использует определенные правила именования, они должны одинаково применяться ко всему API.

Path и query parameters

Path parameter обычно идентифицирует конкретный ресурс
GET /orders/125
где 125 — идентификатор заказа.

Query parameters удобно использовать, например, для фильтрации, сортировки и пагинации:
GET /orders?status=paid&page=2&limit=20
Из документации должно быть понятно, какие параметры обязательны, какие значения допустимы и что произойдет при передаче некорректного значения.

Пагинация

Если коллекция содержит тысячи объектов, возвращать их одним ответом обычно нецелесообразно.

API может использовать, например, page-based подход:
GET /orders?page=2&limit=20
или cursor-based pagination, когда клиент получает указатель для следующей порции данных.

Важно не просто написать «есть пагинация», а описать контракт: параметры, ограничения размера страницы, структуру ответа и способ определения следующей страницы.

Версионирование

API меняется вместе с системой. Если изменение нарушает совместимость с существующими клиентами, возникает вопрос управления версиями. Один из распространенных вариантов:
/api/v1/orders
Однако универсального правила, что версия обязательно должна находиться именно в URL, нет. Конкретную стратегию версионирования команда выбирает исходя из архитектуры и правил проекта.

Для аналитика важнее другое: изменение контракта должно быть управляемым, а потребители API должны понимать, когда и каким образом им необходимо перейти на новую версию.

Пример проектирования API интернет-магазина

Допустим, необходимо спроектировать часть API для работы с заказами.

Получение списка:

GET /orders

Получение заказа:

GET /orders/{id}

Создание:

POST /orders

Частичное изменение:

PATCH /orders/{id}

Удаление — только если бизнес-логика действительно предполагает удаление ресурса:

DELETE /orders/{id}

Для создания заказа тело запроса может выглядеть так:
{
"customerId": 125,
"items": [
{
"productId": 501,
"quantity": 2
},
{
"productId": 730,
"quantity": 1
}
],
"deliveryType": "courier"
}
Но одной структуры JSON недостаточно.

Аналитику необходимо выяснить:
  • может ли заказ содержать недоступный товар;
  • допустимо ли quantity = 0;
  • кто рассчитывает цену;
  • можно ли передавать цену со стороны клиента;
  • какие способы доставки допустимы;
  • какие поля обязательны;
  • что произойдет при повторном запросе;
  • какие бизнес-ошибки может вернуть сервис.

Именно здесь API аналитика превращается из рисования методов в проектирование контракта.

Паттерны проектирования API: HATEOAS и CQRS

ТЗ требует кратко рассмотреть два подхода, которые аналитик может встретить в работе.

HATEOAS

HATEOAS — ограничение REST, при котором сервер вместе с представлением ресурса предоставляет ссылки на доступные дальнейшие действия или связанные ресурсы. Условно ответ для заказа может содержать ссылку на оплату или отмену, если эти действия доступны в текущем состоянии.

Идея состоит в том, что клиент получает информацию о возможных переходах из ответа сервера, а не обязан заранее жестко знать все URI для дальнейших действий. На практике конкретная реализация зависит от архитектуры API, и HATEOAS используется далеко не в каждом REST API.

CQRS

CQRS (Command Query Responsibility Segregation) — архитектурный подход, при котором операции изменения состояния и операции чтения разделяются.

Command изменяет состояние.

Query получает данные.

Важно: CQRS — не специальный паттерн именования REST endpoints и не обязательная характеристика API. Это более широкий архитектурный подход, который может влиять на устройство интерфейсов и модели данных. Для системного аналитика знание CQRS полезно прежде всего тогда, когда API является частью системы, где чтение и изменение данных организованы раздельно.

Тестирование API: что нужно знать системному аналитику

Тестирование API — не только работа QA-инженера. Аналитику не обязательно подменять тестировщика, но понимание способов проверки контракта помогает обнаруживать неоднозначности еще во время проектирования.

Представим требование:

POST /orders создает заказ.

Что нужно проверить? Позитивный сценарий очевиден: передать корректные данные и убедиться, что заказ создан. Но контракт раскрывается именно через дополнительные вопросы:

  • что будет без обязательного customerId;
  • что произойдет при неизвестном productId;
  • можно ли передать отрицательное quantity;
  • что вернется при отсутствии авторизации;
  • какой HTTP status code используется;
  • какой формат имеет тело ошибки.

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

Базовый сценарий проверки в Postman

Для простой проверки аналитик может:

  1. выбрать HTTP-метод;
  2. указать endpoint;
  3. добавить необходимые headers;
  4. передать path/query parameters;
  5. добавить request body для соответствующего метода;
  6. отправить запрос;
  7. проверить status code;
  8. сравнить response body с ожидаемой схемой и бизнес-логикой.

Например, для создания заказа ожидается 201 Created. При некорректных входных данных API может вернуть ошибку класса 4xx. Но конкретный код и структура ответа должны определяться контрактом, а не выбираться аналитиком произвольно после реализации.

Как аналитик участвует в тестировании API

Системный аналитик может:

  • проверять примеры запросов и ответов;
  • сопоставлять реализацию со спецификацией;
  • уточнять бизнес-правила для негативных сценариев;
  • проверять обязательность и допустимые значения параметров;
  • участвовать в разборе расхождений между документацией и фактическим поведением;
  • использовать Postman или аналогичный инструмент для исследовательских запросов.

Так тестирование API становится еще одним способом проверить качество требований и контракта.

Частые ошибки в документации и проектировании API

Описан только успешный ответ

Документация содержит:

200 OK

и ни слова о том, что произойдет при ошибке.

Но интеграции ломаются не только на happy path. Потребителю необходимо понимать, как API сообщает о некорректных параметрах, отсутствии ресурса, проблемах авторизации и бизнес-ограничениях.

Лучше заранее определить структуру ошибок.

Например
{
"code": "PRODUCT_NOT_AVAILABLE",
"message": "Product is not available"
}
Конкретные status codes и error codes должны соответствовать принятому контракту.

Нет примеров запросов и ответов

Схема данных необходима, но конкретный пример помогает быстрее понять реальное использование метода. Особенно это важно для вложенных объектов, массивов, nullable-полей и сложных структур. Хорошая документация сочетает формальное описание с примерами.

Непоследовательное именование

В одном endpoint: customerId
в другом: customer_id
в третьем: clientID.

Даже если каждый метод отдельно работает, API становится сложнее использовать. Правила именования стоит определить заранее и соблюдать последовательно.

Не описаны ограничения

Поле указано как string, но неясно:

может ли оно быть пустым? Есть ли максимальная длина? Какие значения допустимы? Обязательно ли оно?

Тип данных — только часть контракта.

Документация расходится с реализацией

В документации поле обязательное, API принимает запрос без него. В спецификации указан 200, сервис возвращает 201. Пример содержит одну структуру, фактический ответ — другую. Для потребителя API контрактом становится реальное поведение системы, поэтому рассинхронизация документации и реализации особенно опасна.

Документацию необходимо поддерживать вместе с изменениями API.

Как использовать шаблоны API и SWAGGER из AnalystBox

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

При создании документа с нуля приходится заново определять структуру: где описать назначение метода, параметры, request и response, ошибки, ограничения и примеры. Если API содержит много операций, единообразие документации приходится дополнительно контролировать. В наборе AnalystBox предусмотрены два связанных шаблона:

API — для структурированного описания программного интерфейса и правил взаимодействия;

SWAGGER — для работы со структурированным описанием API с пояснениями по заполнению.

Они помогают не начинать оформление с пустого документа и поддерживать единый подход к описанию методов.

Это особенно полезно начинающему системному аналитику: структура одновременно работает как подсказка, какие аспекты контракта стоит проверить перед передачей документации команде.

Главное о документации и проектировании API

Хороший API начинается не со Swagger и не с выбора названия endpoint. Сначала необходимо понять, какие системы взаимодействуют, зачем им это нужно и какой контракт позволит выполнить бизнес-сценарий без неоднозначности.

После этого системный аналитик определяет ресурсы и операции, входные данные, ответы, ошибки и ограничения. OpenAPI помогает формализовать контракт, Swagger и Redoc — работать с его представлением, Postman — отправлять запросы и проверять фактическое поведение.

При этом документация API, проектирование и тестирование связаны между собой. Чем точнее контракт сформулирован на этапе анализа, тем меньше вопросов возникает при разработке интеграции и тем проще проверить результат.

Не начинайте описание каждого API с пустого листа

Чтобы не тратить время на создание документов с нуля, скачайте готовый набор из 13 шаблонов системного аналитика с пояснениями и примерами, включая шаблоны API и SWAGGER.

Получить шаблоны за 2 990 ₽
черный фон с голубым засветом
черный фон с голубым засветом
стеклянная фигура 3д
мужчина держит в руках ноутбук

Как работать с шаблонами

1 шаг Оплатите набор на сайте
2 шаг Скачайте архив с шаблонами
3 шаг Посмотрите структуру, пояснения и примеры
4 шаг Адаптируйте шаблон под задачи своего проекта

13 рабочих шаблонов

GUI · GLOS · ALG · BR · GOAL · FR · Swagger · MEET · API · PASSPORT · DD · NFR · SPIKE

2 бонуса

+ Стандарты ведения документации системными аналитиками
+ Критерии DoR и DoD
Выгодная стоимость шаблонов

Получите готовый набор документов со скидкой 40%

стеклянные документы 3d
Вопросы перед покупкой

Что важно знать о шаблонах