Паспорт одной API-интеграции
Пустой бланк — поля для заполнения обозначены в квадратных скобках.
1. Код интеграции и владельцы сторон
Паспорт относится к одной связи систем с определёнными владельцами. Назовите редакцию и состояние согласования: существование текста не даёт права включить обмен. Для каждой стороны укажите рабочую роль и ответственного за изменение договора, не записывая действующие логины и секреты.
[Код интеграции и владельцы сторон]
2. Цель обмена и исключённые данные
Установите, какой рабочий вопрос решает обмен и какие данные для него действительно нужны. Отдельно исключите лишние поля и процессы. Получение технического доступа не подтверждает законность любого последующего использования сведений; основание и условия обработки проверяются отдельно.
[Цель обмена и исключённые данные]
3. Среды, адрес документации и версия API
Запишите точную версию интерфейса и ссылку на доступную документацию, различайте тестовый и рабочий контуры. Адрес в примере вымышленный и не является работающим сервисом. Смена версии или схемы оформляется как новое согласованное состояние, а не незаметная правка паспорта.
[Среды, адрес документации и версия API]
4. Операции, направления и схема полей
Опишите каждую разрешённую операцию, направление и смысл полей, включая пустое, отсутствующее и нулевое значение. Сопоставление выполняют по идентификатору, а не похожему названию товара. Операции изменения данных не предполагаются из наличия чтения и требуют отдельного описания.
[Операции, направления и схема полей]
5. Способ авторизации и место управления
Назовите механизм авторизации, минимальный набор прав, владельца и принятый канал управления секретом. Не вставляйте значение ключа даже в демонстрационный журнал. Срок действия и отзыв проверяют в реальной системе; ссылка на хранилище сама по себе не подтверждает правильную выдачу прав.
[Способ авторизации и место управления]
6. Расписание, лимиты и остановка запросов
Сверьте частоту, размер страницы и ограничения с текущей документацией именно этого API. Не переносите числовые квоты другого провайдера. Если ответ сообщает ожидание, зафиксируйте его применение и предел числа попыток; бесконечные повторы и увеличение параллельности не считаются обработкой ограничения.
[Расписание, лимиты и остановка запросов]
7. Ошибки, повторы и повторное событие
Разделяйте временную ошибку, отказ в доступе и несовместимость схемы. Для каждой укажите безопасное следующее действие и условия прекращения повторов. Повтор операции изменения может создать дубликат или списание; допустимость повтора подтверждают договором и идентификатором операции, а не надеждой на одинаковый ответ.
[Ошибки, повторы и повторное событие]
8. Проверки обмена и наблюдаемость
Перечислите сценарии и ожидаемые реакции до подключения. В журнале оставляйте достаточные для диагностики идентификаторы без токенов и лишнего содержимого. Наличие успешного ответа не подтверждает правильное сопоставление; проверяйте действие на тестовом наборе, пагинацию и недоступность запрещённых операций.
[Проверки обмена и наблюдаемость]
9. Поведение при недоступности и ручной режим
Определите, что увидит пользователь при просроченном или отсутствующем ответе. Не подменяйте неизвестное нулём и не скрывайте возраст кэша. Ручная обходная процедура должна иметь владельца и следы выполнения; она не расширяет автоматически полномочия интеграции и не отменяет ограничения данных.
[Поведение при недоступности и ручной режим]
10. Изменения, отзыв и состояние включения
Сохраните дату согласования, фактическое состояние включения и порядок изменения или отключения. Выключенный код может оставлять активный токен, подписку или фоновое задание; эти элементы проверяют отдельно. Подтверждение владельцев относится к конкретной редакции, а не ко всем будущим версиям API.
[Изменения, отзыв и состояние включения]