API: контракты и правила обмена

Подготовьте спецификацию и доступ

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

До разработки запросите спецификацию именно вашего контура, тестовую среду и порядок выдачи доступа. Зафиксируйте версию документа и согласуйте сценарий с техническим владельцем. Только выданный контракт определяет URL, поля, ограничения и коды ответов.

Проверьте полноту контракта

Если поле допускает пустое значение, уточните различие между отсутствием поля и явной очисткой. Для даты согласуйте формат и часовой пояс, для числового значения — единицу измерения и точность. Такие детали влияют на данные сильнее, чем форма запроса.

Передавайте контекст и проверяйте полномочия

Для операции должен быть определён действующий субъект и организационный контекст. Способ передачи — часть контракта: не предполагайте конкретный заголовок или тип токена. Уточните область прав, срок действия и процедуру обновления учётных данных.

Право на основной объект не следует распространять на связанные записи автоматически. При чтении сделки, документа или назначенного курса проверьте, что возвращаемые связи и вложения находятся в разрешённом контексте. Отрицательные сценарии включите в приёмку.

• Разрешённая операция в своей организации.
• Та же операция с недостаточными правами.
• Прямое обращение к чужому объекту или связанной записи.
• Повтор операции после отзыва полномочий.
• Выборка и экспорт с учётом прав на строки и поля.

Согласуйте модель объекта и связи

Внешняя модель должна позволять сопоставить запись, определить её тип и версию, сохранить связь с источником. Для расширяемых сущностей уточните описание схемы дополнительных полей, правила валидации и совместимость версий. Не превращайте предположения о внутренней базе в контракт обмена.

{
  "organization_ref": "example-organization",
  "external_ref": "source-record-42",
  "object_type": "example-document",
  "revision": "example-revision",
  "related_source_ref": "source-process-17"
}

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

Если объект меняется одновременно в нескольких системах, определите источник истины по полям. Версия записи помогает обнаружить конфликт, но правила его обработки должны быть явно описаны.

Изменения, идемпотентность и неопределённый результат

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

После обрыва соединения или таймаута нельзя считать операцию ни успешной, ни неуспешной без дополнительной проверки. Используйте предусмотренный контрактом способ выяснить результат; если его нет, согласуйте порядок ручного разбора до промышленного запуска.

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

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

Различайте ошибки по способу исправления

Это смысловые классы, а не обещание конкретных HTTP-кодов. Сопоставление ответов с ними делайте по выданной спецификации. Сохраните диагностический идентификатор ответа, если он предусмотрен, и исключите секреты из сообщения об ошибке.

Выборки, события и эксплуатация

Для пагинации уточните устойчивость порядка и поведение при изменении данных между страницами. Проверьте, что обработчик не теряет и не дублирует записи при переходе к следующей порции. При больших объёмах согласуйте ограничение выборки и способ возобновления.

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

Для диагностики цепочки запросов согласуйте идентификаторы операции и корреляции. Журнал должен связывать исходное событие с результатом, но не хранить токены, пароли и полные персональные данные без необходимости. Перед приёмкой испытайте отказ доступа, конфликт, повтор, частичную обработку и восстановление.