Чтобы принять API-модуль, мало согласовать формат данных. Нужно описать, что означает операция, кто её вызывает, какие изменения допустимы и как две команды проверят результат вместе. Тогда предметом субподряда становится законченный модуль, а не набор часов разработчика.
Сначала определите границу модуля
API — программный интерфейс, через который части системы обращаются друг к другу. Его потребителем может быть кабинет, мобильное приложение или другой сервис. Для каждого потребителя важно сохранить не только возможность прочитать ответ, но и смысл следующего действия.
Рассмотрим учебный пример. В кабинете партнёра уже есть черновики заявок. Внешней команде поручают модуль передачи выбранной редакции заявки на обработку. Создание черновика, расчёт цены и подтверждение заказа остаются в основном продукте. Результат модуля — зарегистрированная передача конкретной редакции, доступная основной команде.
Это техническая граница. Вопрос, зачем бизнесу нужен такой обмен, решается раньше. Здесь разберём, как передать выбранный участок подрядчику, не оставив между командами неопределённых обязанностей.
Паспорт одной операции
Для учебного модуля договоримся о следующем поведении. Названия полей, статусы и номера версий ниже придуманы для примера; это не интерфейс действующего продукта.
| Что фиксируем | Договорённость в примере |
|---|---|
| Операция | Передать редакцию черновика на обработку |
| Кто вызывает | Кабинет партнёра от имени пользователя с правом на эту заявку |
| Вход | Номер заявки, ожидаемая ревизия и ключ операции |
| Источник данных | Состав заявки и её текущая ревизия хранятся в основном сервисе |
| Выход | Номер операции, принятая ревизия и состояние «передана на обработку» |
| Что успех не означает | Заказ ещё не подтверждён менеджером и не выполнен |
| Ошибки | Нет права, неверные данные, устаревшая ревизия или конфликт ключа операции |
| Версия | Версия интерфейса v1 отдельно от ревизии содержимого заявки |
| Повтор | Тот же ключ и прежние входные данные возвращают сохранённый результат в пределах согласованного срока хранения |
Пример тела запроса на передачу заявки:
{
"request_id": "request-demo-17",
"expected_revision": 3,
"operation_id": "submit-demo-17-r3"
}Пример успешного ответа:
{
"operation_id": "submit-demo-17-r3",
"request_id": "request-demo-17",
"accepted_revision": 3,
"status": "submitted"
}В этом контракте submitted означает только принятие редакции к обработке. Отдельно описываются HTTP-метод, путь, правила доступа и коды ответов. В OpenAPI 3.1.1 для этого предусмотрены описание операции, входные параметры и тело запроса, ответы и их содержимое. Документация должна охватывать успешный ответ и известные ошибки. Она не заменяет договорённость о смысле статуса.
Два случая важно развести. Повтор уже принятой операции должен находить прежний результат, даже если заявка позже изменилась. Но новый запрос на старую ревизию не должен подтверждать новое содержимое. Если под уже использованным ключом прислали другие данные, это конфликт, а не повтор. Порядок этих проверок входит в контракт.
Кто отвечает за каждую часть
Матрица ниже — пример распределения работы, который стороны уточняют до разработки. «Согласуем вместе» полезно дополнить именем принимающего специалиста: иначе решение может зависнуть между командами.
| Участок | Команда партнёра | Подрядчик модуля |
|---|---|---|
| Доступы и данные | Предоставляет разрешённую тестовую среду и примеры, определяет права | Запрашивает нужный минимум, не требует рабочую базу по умолчанию |
| Контракт | Подтверждает смысл операции и требования потребителей | Описывает запросы, ответы, ошибки и ограничения модуля |
| Реализация | Поддерживает зависимости вне переданного участка | Реализует согласованный код модуля и его проверки |
| Потребитель API | Обеспечивает совместимую версию вызывающего приложения | Передаёт контрольные запросы и примеры ответов |
| Проверка кода и приёмка | Назначает специалиста для ревью и принимает совместный сценарий | Показывает изменения, воспроизводит проверки, устраняет несоответствия |
| Выпуск | Назначает ответственного за включение модуля в общий продукт | Передаёт сборку, зависимости и инструкцию подключения |
Когда за стороннюю систему отвечает ещё один исполнитель, его действия также нужно включить в план. Наличие документации API не означает, что нужные доступы уже выданы или что другая команда выпустит изменения одновременно.
Три пары изменений: совместимо или нет
Одинаковый JSON не гарантирует одинакового поведения. Сначала перечислите потребителей и проверьте, какие предположения заложены в их коде.
| Что меняется | Может сохранить совместимость | Нарушает прежнюю договорённость |
|---|---|---|
| Поле | Добавлено необязательное поле ответа, а потребители по контракту допускают неизвестные поля | Прежнее необязательное поле запроса стало обязательным или у существующего поля изменился тип |
| Смысл статуса | Пояснение расширено, но submitted по-прежнему означает передачу на обработку | Под тем же статусом теперь подразумевается подтверждённый заказ |
| Порядок и округление | Новый порядок доступен по отдельному параметру; прежний порядок и правила расчёта сохранены | По умолчанию поменялся порядок списка или округление суммы, на которые опирается потребитель |
Даже добавление поля нельзя автоматически считать безопасным: строгий потребитель может отвергнуть незнакомое значение. Примеры в таблице работают только при названных условиях. Для списков отдельно проверяют переход между страницами: изменение сортировки не должно незаметно пропускать или повторять записи в принятом сценарии.
Принимайте контракт вместе с потребителем
Сохраните рядом с контрактом входные примеры и ожидаемые ответы. Для нашего модуля нужны успешная передача редакции, повтор уже принятой операции, конфликт ключа с другими данными, новая попытка со старой ревизией и запрос без нужного права. Если доступ к зависимости пропадает, должен получиться предусмотренный результат, а не случайный ответ библиотеки.
Проверку совместимости полезно повторять автоматически при изменениях. При этом сравнение структуры ответа — лишь один уровень. Основное приложение должно правильно обработать ответ: показать передачу на рассмотрение, а не окончательное подтверждение заказа. Для описания наблюдаемого результата подходят Критерии готовности рабочего сценария.
Перед проверкой стороны фиксируют версии модуля и потребителя, тестовые данные, способ сборки и ожидаемые состояния. После неё сохраняют результат каждого сценария и обнаруженные ограничения. Это позволяет другой команде повторить проверку, а не доверять только записи демонстрации.
Если интерфейс заменяет старую версию, заранее определяют переходный период и владельцев потребителей. До отключения старого варианта проверяют, кто продолжает его использовать. Срок вывода версии согласуется с этими командами, а не назначается по факту готовности нового кода.
Что передать вместе с кодом
Комплект модуля включает согласованный контракт, исходный код, контрольные запросы и ответы, результаты проверок, зависимости сборки и инструкцию подключения. Отдельно нужны условия выпуска и возврата: какие действия выполняет каждая сторона и что делать с операциями, принятыми новой версией.
Порядок приёмки и передачи помогает связать эти материалы с результатом этапа. Переданный модуль не означает принятия ответственности за весь продукт партнёра, но его собственные границы не должны оставаться неясными.
По теме: Подготовить бизнес-задачу обмена.
Для первого обсуждения достаточно описать операцию, её потребителей и результат, который они должны получить. Рабочие доступы и секреты для этого не нужны; закрытые материалы передаются отдельно по согласованному порядку.
