API release contracts: what C0, C1, C2, C3 and C4 guarantee

"Use only released APIs" is the most repeated rule in ABAP Cloud and Clean Core. But released how, for whom and with what guarantee? An SAP object can be released for ABAP Cloud and not for the Key User apps, or the other way round. It can be released for remote use and not for use in the system itself. And a Z object released by the company does not have the same protection as an object released by SAP. All of this is in the release contract.

What a release contract is

A release contract is a classification that the owner of an ABAP repository object assigns to it to declare it an API. It has two parts:

• the contract, which states what can no longer change in the object and what kind of use it is meant for;
• the visibility, which states which language versions can use it: ABAP for Cloud Development, ABAP for Key Users or both.

Without a contract, an SAP object cannot be used by ABAP Cloud code or by Key User code. The contract is what turns a table, CDS view, class or function module into a "released API".

The five contracts

C4 is the newest: it appears in the ABAP 7.58 documentation (S/4HANA 2023) and not in 7.57. In a measured S/4HANA 2023 (SP00) system, only four SAP objects had C4. C1 is by far the most common: it decides what ABAP Cloud code and Key User code can use.

Visibility: ABAP Cloud, Key User or both

Only C0 and C1 have visibility. For C1, the two options are:

The two are independent, and the difference is not a detail. In a measured S/4HANA 2023 (SP00) system, the SAP objects released with C1 were split as follows:

There are more objects released only for Key User than only for ABAP Cloud. Among CDS views alone, 3,429 were Key User only against 1,031 Cloud only. A CDS view such as I_BudgetEntryDocumentType can be read by a Custom CDS View, but an ABAP Cloud class that tries to read it gets "The use of CDS Entity ... is not permitted". Released function modules, on the other hand, are always ABAP Cloud only: the documentation states that a function module cannot be released for Key User.

Visibility is tied to the language version, not to a software component. An object released for Cloud Development can be used by any ABAP Cloud code in the system.

What changes after the release

Releasing is promising stability. SAP's rules for C1 state what can no longer change:

• CDS views: no field, parameter or association to a released target can be removed, and only non-key fields can be added. The case of names and the client handling cannot change, and implicit SELECT * is forbidden;
• classes and interfaces: the class must be final or abstract, with private instantiation. No method can be deleted, changed from static to instance or reduced in visibility. A new optional parameter is allowed, but it cannot become mandatory;
• function modules: the parameters do not change, optional ones can be added and new exceptions cannot;
• dictionary: no field can be removed from a structure or table, and no domain can be shortened. A table type cannot change at all;
• any C1 object: it cannot be deleted after release. The way out is to mark it as deprecated, with a successor.

C2 adds the ban on lengthening fields, and C4 allows no change at all.

Who prevents an incompatible change

This is the point that is most often confused. For SAP objects, compliance with the contract is verified by special ATC checks, within SAP's own development process, before each delivery.

For the objects the company releases, protection also comes from the ATC, not from activation. There are two checks:

• API_COMPATIBILITY (API Release: Compatibility of Released APIs), which compares the object with a snapshot of the API taken earlier in the Manage API Snapshots app, which also exists in S/4HANA on-premise. Without a snapshot, it reports nothing;
• API_CONSISTENCY (API Release: Consistency of Released APIs), which checks the contract rules.

In an S/4HANA 2023 system without that snapshot configured, activation accepted the following on a Z object released with C1:

• removing a field from a CDS view;
• deleting the only public method of a class;
• releasing a CREATE PUBLIC class, against the private instantiation rule;
• removing the Key User visibility from an already released CDS view.

None of these changes caused an error. In other words, C1 on a Z object is a promise made by whoever releases it, and the system only enforces it if the compatibility ATC check is in use. Whoever releases Z objects for other teams needs three things: an approval process, which SAP itself recommends, these checks in the ATC check variant, and an API snapshot taken for every released version.

Release states and the successor

The successor is the most useful part for those adapting classic code. It appears in the syntax message itself: reading table T001 in ABAP Cloud code gives "The use of Table T001 is not permitted. Use CDS Entity I_COMPANYCODE instead.". An object can have more than one successor: MARA has five (I_Product, I_ProductQM, I_ProductSales, I_ProductStorage_2 and I_ProductProcurement), and the choice depends on the fields the program uses.

Where to look up an object's state

• In ADT: the API State tab, in the object's properties, shows contract, state, visibility and successor. A repository tree with the api: filter lists objects by contract (for example api:USE_IN_KEY_USER_APPS).
• In the system: program ABAP_DOCU_RELEASED_APIS lists the objects with a contract. Table ARS_W_API_STATE holds one row per object and contract, with the columns USE_IN_SAP_CLOUD_PLATFORM and USE_IN_KEY_USER_APPS for visibility.
• On SAP's GitHub: the Cloudification Repository (SAP/abap-atc-cr-cv-s4hc) has one file per release with the released objects, the objects not released and the successors. The file has no contract or visibility and only lists what is visible to ABAP Cloud. A CDS view released only for Key User does not appear in it: for Key User, the source is the system itself.

Releasing your own object

The company can release its own objects with C0 (Cloud Development only) and with C1, with either visibility. The release is done in ADT, through the API State tab or the Change API State menu, and travels with the object in the transport request as an object of its own (R3TR APIS). The comment written in the release wizard stays only in the source system and is not transported.

The most common use is the wrapper: an object in Standard ABAP that uses something not released and exposes itself with C1 to the ABAP Cloud code of another software component. The release allows the use, but it does not change the object's own Clean Core findings. The details are in Software components in ABAP Cloud: who can call whom and in Wrappers in Clean Core: the debt is concentrated, not removed. Key User visibility, and what it opens up, is covered in ABAP for Key Users: what key user objects are and where they fit in Clean Core.

Sources

• SAP Help, ABAP Keyword Documentation 7.58: ABAP Language Versions, Release Contracts and Released APIs, the glossary entries for contracts C0 to C4 and the C1 Contract Rules for API Providers (CDS, ABAP objects and dictionary). Version 7.57 of the same page, for the C4 comparison.
• SAP Help, ABAP Development Tools User Guide: Released APIs, Releasing Development Objects, the pages for each contract, Deprecation and Checking the Compatibility of Released APIs.
• SAP Help, SAP BTP ABAP Environment: Software Component Dependencies and API Release Framework.
• SAP, Cloudification Repository (GitHub SAP/abap-atc-cr-cv-s4hc).
• Queries on table ARS_W_API_STATE and release tests in SAP S/4HANA 2023 (SAP_BASIS 758).