Контракты интеграционных интерфейсов и изменение версий#

Интерфейс - это обещание потребителю о структуре данных, смысле полей, фильтрах, порядке, ошибках и сроке поддержки. OpenAPI-файл или имя API описывает только часть этого обещания. В финансовой интеграции контракт дополнительно задаёт ключи, валюты, даты, семантику удалений, повторную доставку и сверки. Пример извлечения SAP-журнала и передачи в хранилище приведён в статье SAP Journal в Financial DWH.

Запишите контракт до реализации#

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

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

Классифицируйте изменения по их эффекту#

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

Перед выпуском оцените как минимум:

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

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

Планируйте миграцию и вывод из эксплуатации#

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

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

Не смешивайте механизмы SAP#

Документация SAP различает версии API, показываемые в SAP Business Accelerator Hub, версии и ревизии прокси в SAP API Management и release contract опубликованных ABAP API. В описании версии SAP Business Accelerator Hub используются major/minor/patch и разные категории изменений; API Management описывает revision для совместимых изменений одного прокси и version для несовместимого перехода. Для опубликованных ABAP API стабильность зависит от release contract; API snapshots и проверка совместимости применяются в соответствующем контексте ABAP Environment. Эти механизмы относятся к разным объектам и продуктам: не переносите их правила на любой SAP endpoint или CDS view.

В API Management статусы прокси, включая deprecated и decommissioned, являются состояниями прокси. Наличие статуса само по себе не подтверждает, что все потребители мигрировали, что задана одинаковая политика поддержки в целевом SAP-продукте или что выключение безопасно. Проверяйте версию, статус, документацию и сроки именно у выбранного интерфейса и в целевом продукте и релизе.

Минимальный набор проверок#

1. Проверьте обязательные поля, типы, диапазоны, пустые значения и неизвестные значения перечислений.
2. Прогоните старые и новые контрактные примеры через каждого известного потребителя.
3. Проверьте ключ, повторы, перестановку событий, исправление задним числом, отмену и сверку сумм по валюте и периоду.
4. Сверьте схему, документацию, версию SAP, авторизацию, фильтры и лимиты с фактическим интерфейсом целевого релиза.
5. Выполните переключение и откат в тестовом окружении, включая восстановление checkpoint и повторную поставку.

Эта статья описывает методику проектирования и контроля контрактов. В проекте нет SAP runtime, живых API-потребителей или проверок совместимости конкретного интерфейса. Приведённые ссылки относятся к названным механизмам SAP и не подтверждают доступность одного и того же API во всех редакциях и релизах.

Interface contracts promise consumers a data structure, field meaning, filters, ordering, errors, and a support period. An OpenAPI file or API name describes only part of that promise. A financial integration also needs keys, currencies, dates, deletion semantics, replay behavior, and reconciliation. See SAP Journal in Financial EDWH for an extraction example.

Record the contract#

For each interface, record its owner and consumers; product, edition, and release; access path; schema; meaning of each date and amount; row key; filtering; replay behavior; ordering and version marker; deletion and correction rules; error codes; limits; authorization; and the period during which versions coexist. Track the source product version separately from the consumer contract version. A SAP release change does not automatically imply a payload change, and an unchanged URL does not guarantee unchanged behavior under different filters or permissions.

Keep representative messages, expected results, and known exceptions with the contract. Financial examples should include negative and zero amounts, multiple currency valuations, a late correction, a cancellation, and an empty result. Examples do not replace the schema or a check against the target release.

Classify changes by consumer effect#

Compatibility depends on the named consumers and their parsing rules. Adding an optional field may break a consumer that rejects unknown properties; renaming a field usually breaks a client that reads it. A new enumeration value, changed unit or date meaning, narrower filter, different rounding, or altered row order can change calculations even when the JSON shape stays the same.

Before release, assess at least:

1. Presence and type of every field, requiredness, nulls, and defaults.
2. Monetary precision and units, currency, sign, date, and time zone.
3. Row granularity, key composition, uniqueness, and ordering.
4. Filters, completeness, pagination, and error codes.
5. Replays, late events, deletions, and checkpoint recovery.
6. Authorization, limits, and the period of parallel version support.

Automate schema comparison, but do not treat it as proof of semantic compatibility. Generate representative old and new responses for consumers and check business invariants against both. A silent change to a field's value with its type unchanged can be more dangerous than an explicit schema change.

Plan migration and retirement#

For an incompatible change, publish a separate contract or version with a clear migration path. Operate old and new versions in parallel for an announced period. Name the successor, differences, support end date, and shutdown date, and assign migration owners. Measure old-version use by consumer. Before shutdown, verify that traffic has stopped, reconciliations are complete, and replay remains possible.

Rolling back a consumer does not reverse financial data already applied. Preserve the input delivery and contract version, application results, rejected rows, and an agreed recalculation procedure. Test incompatibility before production cutover, not while resolving a close-period discrepancy.

Keep SAP mechanisms distinct#

SAP documentation describes API versions on SAP Business Accelerator Hub, versions and revisions of proxies in SAP API Management, and release contracts for released ABAP APIs. The Business Accelerator Hub version description uses major, minor, and patch categories. API Management describes a revision for compatible changes to a proxy and a version for an incompatible transition. Stability for released ABAP APIs depends on their release contract; API snapshots and compatibility checks apply in the corresponding ABAP Environment context. These mechanisms govern different objects and products. Do not transfer their rules to every SAP endpoint or CDS view.

In API Management, deprecated and decommissioned are proxy states. A status alone does not prove that consumers migrated, that the target SAP product has the same support policy, or that shutdown is safe. Check version, status, documentation, and dates for the selected interface and target product release.

Minimum checks#

1. Validate required fields, types, ranges, nulls, and unknown enumeration values.
2. Run old and new contract examples through every known consumer.
3. Check keys, replay, reordered events, late corrections, cancellation, and reconciliation by currency and period.
4. Compare schema, documentation, product release, authorization, filters, and limits with the target interface.
5. Exercise cutover and rollback in a test environment, including checkpoint recovery and replay.

This article describes a design method. No SAP runtime, live API consumer, or compatibility check for a specific interface was available. The cited SAP mechanisms do not establish availability across all editions and releases.