Released APIs и OData: контракты финансовых сервисов#

В SAP слово API может обозначать тип ABAP-объекта, разрешение на его использование или опубликованный сетевой сервис. Это разные контракты. Для финансового обмена важно знать, кто вправе вызывать объект, каким способом, с какой семантикой данных и какое изменение совместимо с уже работающим потребителем.

Не смешивайте release state и release contract#

Статус Released, Deprecated или Decommissioned сообщает состояние жизненного цикла объекта. Release contract задаёт цель разрешённого использования и требования стабильности. В документации ABAP Cloud перечислены, среди прочего, C0 для расширения, C1 для внутреннего использования в разработке и C2 для удалённого API; назначение и доступность зависят от типа объекта, языка ABAP и продуктового контекста. Не выводите пригодность внешнего потребителя из одного слова Released.

Для каждого используемого SAP-объекта проверьте в целевой системе:

существует ли он в установленном выпуске и компоненте;
какой у него API state, release contract и видимость;
разрешён ли контракту именно ваш способ вызова: ABAP-код, расширение или удалённый клиент;
проходят ли проверки ATC и актуальные правила совместимости;
какой преемник и план обновления указаны для устаревающего объекта.

Классификация release относится к объекту в определённом software component и пакете. Она не доказывает, что такой же объект доступен во всех редакциях S/4HANA или во всех релизах. Проверьте опубликованный API в каталоге и системе проекта, а не только по совпадению имени в статье или примере.

Слои RAP-сервиса и OData#

В RAP разделены бизнес-модель и протокол публикации. CDS-модель задаёт данные и связи; service definition выбирает, что входит в бизнес-сервис; service binding связывает это определение с протоколом и способом предоставления, например OData V2 или V4 и UI-service либо Web API. Одна service definition может участвовать в разных bindings. Поэтому UI-представление не следует автоматически считать стабильным внешним API для интеграционного клиента.

В редакторе binding сервис активируют и публикуют для текущей ABAP-системы. Такая локальная публикация сама по себе не создаёт доступ из другого ландшафта и не настраивает маршрутизацию, TLS, доверие, аутентификацию, роли или сетевой доступ. Внешний потребитель требует отдельной конфигурации транспортного и защитного контура.

Для OData фиксируйте в контракте:

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

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

Версия и совместимость#

Сервисная версия должна позволять старому клиенту продолжить работу, пока потребитель отдельно не согласовал переход. SAP описывает версионирование в service binding через service definitions и сервисные версии; детали именования, API state и семантической версии зависят от типа binding и релиза. Перед добавлением или удалением версии проверьте, как её адресуют клиенты и что происходит с прежней.

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

Доступ, конкуренция и повторная доставка#

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

RAP ETag обеспечивает optimistic concurrency: клиент присылает версию прочитанного экземпляра, а система принимает изменение только при совпадении с актуальным состоянием. Это помогает обнаружить конкурирующее изменение, но не задаёт бизнес-правила повтора, дедупликации или сверки. Проверяйте ETag на чтении и записи, включая устаревший клиентский токен, а draft-сценарий оценивайте отдельно.

Проверка финансового сервиса#

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

Записывайте систему, редакцию и выпуск, binding type, service definition, версию, пользователя или роль, параметры запроса, тестовые данные и точные ожидаемый и фактический результаты. Успешная проверка metadata подтверждает описание сервиса, но не полномочия, корректность финансового расчёта или поведение интеграции под нагрузкой.

Область источников и проверки#

Документация по контрактам API и service definition относится к ABAP Cloud / ABAP Cross-Product; описание Service Binding ограничено ABAP Platform 2025 FPS01. Перед применением перепроверьте функции и типы binding в целевой редакции и выпуске. Записи источников имеют статус metadata_only, сохранённые снимки отсутствуют. Сервис, роли, клиентский контракт, финансовые операции и SAP runtime в этом проекте не запускались.

Released APIs and OData: financial service contracts#

In SAP, API can mean an ABAP repository object, permission to use that object, or a published network service. These are different contracts. For financial exchange, establish who may call the object, through which interface, with what data semantics, and which changes remain compatible with existing consumers.

Do not confuse API state with release contract#

Released, Deprecated, and Decommissioned describe lifecycle state. A release contract describes the permitted purpose and stability requirements. ABAP Cloud documentation includes C0 for extensions, C1 for internal development use, and C2 for remote APIs, among others. Purpose and availability depend on object type, ABAP language version, and product context. The word Released alone does not establish suitability for an external consumer.

For every SAP object, check in the target system:

Is it present in the installed release and component?
What are its API state, release contract, and visibility?
Does that contract permit this use: ABAP code, extension, or remote client?
Do ATC and current compatibility checks pass?
What successor and migration path are provided for deprecated objects?

A release classification applies to an object in a particular software component and package. It does not prove that an identically named object exists in every S/4HANA edition or release. Check the API catalog and project system, not just a matching name in an article or example.

RAP service layers and OData#

RAP separates the business model from its exposure protocol. A CDS model defines data and relationships; a service definition selects what belongs to the business service; a service binding connects that definition to a protocol and purpose, for example OData V2 or V4 and a UI service or Web API. One service definition can participate in different bindings. A UI surface should not automatically be treated as a stable external integration API.

In the binding editor, a service is activated and published for the current ABAP system. Local publication does not by itself create access from another landscape or configure routing, TLS, trust, authentication, roles, or network access. An external consumer needs a separately configured transport and security path.

Specify these items in an OData contract:

public entity sets, keys, associations, and available operations;
amount and currency types, quantities and units, dates and time zones;
filters, sorting, pagination, and expected response size;
who can read or change each financial record;
business error structure and retry conditions;
concurrent update behavior and command idempotency rules.

Do not rely on accidental fields from an internal CDS model as the public contract. A stable service exposes only the required business surface and preserves the meaning of its keys and measures.

Versioning and compatibility#

A service version should allow an existing client to continue until the consumer has agreed to migrate. SAP documents service versioning in a service binding through service definitions and service versions; naming, API state, and semantic version details depend on binding type and release. Before adding or removing a version, check how clients address it and what happens to the previous version.

A change can be technically permitted yet incompatible in business meaning. Changing the currency basis of an amount, row detail, key, company filter, reversal rules, or treatment of empty values can change a report even if its JSON schema is unchanged. Keep control examples and compare old and new versions using the same input set.

Access, concurrency, and redelivery#

Check authorization along the actual consumption path: application roles, DCL, and business-object permissions must restrict the data returned to the client. For modifying requests, define retry behavior after a timeout so that repeating a command does not create a second financial effect. Not every operation is safe to repeat; an idempotency key or business check must be an explicit part of the chosen contract.

RAP ETags provide optimistic concurrency: the client sends the version it read, and the system accepts a change only if that version still matches the current state. This detects a competing change, but does not define business retry, deduplication, or reconciliation rules. Test ETags on reads and writes, including a stale client token, and assess draft behavior separately.

Test a financial service#

For each consumer, keep a matrix of version, operation, role, and expected result. Include reads for allowed and disallowed companies, filtering and pagination, currencies with different precision, a fiscal-period boundary, repeating the same command, a timeout after submission, and two concurrent updates to one object. Reconcile more than the HTTP status: document and item identifiers, amounts, currencies, posting status, and control totals also matter.

Record the system, edition and release, binding type, service definition and version, user or role, request parameters, test data, and exact expected and actual results. A successful metadata check confirms the service description, not authorization, financial correctness, or behavior under integration load.

Source and verification scope#

The API-contract and service-definition documents refer to ABAP Cloud / ABAP Cross-Product; the Service Binding description is scoped to ABAP Platform 2025 FPS01. Check features and binding types in the target edition and release before applying them. Source records are metadata_only, with no retained snapshots. No service, roles, consumer contract, financial operation, or SAP runtime was used in this project.