Contratos de liberación de API: qué garantizan C0, C1, C2, C3 y C4

"Use solo API liberada" es la regla más repetida de ABAP Cloud y de Clean Core. Pero ¿liberada cómo, para quién y con qué garantía? Un objeto de SAP puede estar liberado para ABAP Cloud y no para las apps de Key User, o al revés. Puede estar liberado para uso remoto y no para uso en el propio sistema. Y un objeto Z liberado por la empresa no tiene la misma protección que un objeto liberado por SAP. Todo eso está en el contrato de liberación.

Qué es un contrato de liberación

Un contrato de liberación (release contract) es una clasificación que el dueño de un objeto del repositorio ABAP le asigna para declararlo API. Tiene dos partes:

• el contrato, que indica lo que ya no puede cambiar en el objeto y para qué tipo de uso sirve;
• la visibilidad, que indica qué versiones de lenguaje pueden usarlo: ABAP for Cloud Development, ABAP for Key Users o ambas.

Sin contrato, un objeto de SAP no puede ser usado por código ABAP Cloud ni por código de Key User. Es el contrato lo que convierte una tabla, una CDS, una clase o una función en una "API liberada".

Los cinco contratos

El C4 es el más reciente: aparece en la documentación de ABAP 7.58 (S/4HANA 2023) y no en la 7.57. En un S/4HANA 2023 (SP00) medido, solo cuatro objetos de SAP tenían C4. El C1 es, con diferencia, el más común: es el que decide lo que el código ABAP Cloud y el código de Key User pueden usar.

Visibilidad: ABAP Cloud, Key User o ambos

Solo el C0 y el C1 tienen visibilidad. En el C1, las dos opciones son:

Las dos son independientes, y la diferencia no es un detalle. En un S/4HANA 2023 (SP00) medido, los objetos de SAP liberados en C1 se repartían así:

Hay más objetos liberados solo para Key User que solo para ABAP Cloud. Solo entre las CDS, había 3.429 solo para Key User frente a 1.031 solo para Cloud. Una CDS como I_BudgetEntryDocumentType puede ser leída por una Custom CDS View, pero una clase ABAP Cloud que intenta leerla recibe "The use of CDS Entity ... is not permitted". En cambio, los módulos de función liberados son siempre solo para ABAP Cloud: la documentación dice que una función no puede liberarse para Key User.

La visibilidad está ligada a la versión de lenguaje, no a un componente de software. Un objeto liberado para Cloud Development puede ser usado por cualquier código ABAP Cloud del sistema.

Qué cambia después de la liberación

Liberar es prometer estabilidad. Las reglas de SAP para el C1 indican lo que ya no puede cambiar:

• CDS: no se quitan campos, parámetros ni asociaciones a destinos liberados, y solo se añaden campos que no son clave. No se cambian las mayúsculas y minúsculas de los nombres ni el tratamiento del mandante, y el SELECT * implícito está prohibido;
• clases e interfaces: la clase debe ser final o abstracta, con instanciación privada. No se borran métodos, no se cambia de estático a instancia ni se reduce la visibilidad. Se permite un parámetro opcional nuevo, pero no puede volverse obligatorio;
• módulos de función: los parámetros no cambian, pueden añadirse opcionales y no se añaden excepciones nuevas;
• diccionario: no se elimina ningún campo de una estructura o tabla, y no se acorta un dominio. Un tipo de tabla no cambia en nada;
• cualquier objeto C1: no puede borrarse después de liberado. El camino es marcarlo como obsoleto, con un sucesor.

El C2 añade la prohibición de alargar campos, y el C4 no permite ningún cambio.

Quién impide un cambio incompatible

Este es el punto que más se confunde. Para los objetos de SAP, el cumplimiento del contrato lo verifican checks especiales del ATC, dentro del proceso de desarrollo de la propia SAP, antes de cada entrega.

Para los objetos que libera la empresa, la protección también es del ATC, y no de la activación. Los checks son dos:

• API_COMPATIBILITY (API Release: Compatibility of Released APIs), que compara el objeto con una instantánea de la API (snapshot) tomada antes en la app Manage API Snapshots, que también existe en S/4HANA on-premise. Sin la instantánea, no señala nada;
• API_CONSISTENCY (API Release: Consistency of Released APIs), que comprueba las reglas del contrato.

En un S/4HANA 2023 sin esa instantánea configurada, la activación aceptó, en un objeto Z liberado en C1:

• quitar un campo de una CDS;
• borrar el único método público de una clase;
• liberar una clase CREATE PUBLIC, en contra de la regla de instanciación privada;
• quitar la visibilidad Key User de una CDS ya liberada.

Ninguno de estos cambios dio error. Es decir: el C1 en un objeto Z es una promesa de quien libera, y el sistema solo la exige si el ATC de compatibilidad está en uso. Quien libera objetos Z para otros equipos necesita tres cosas: un proceso de aprobación, que la propia SAP recomienda, esos checks en la variante del ATC y una instantánea de la API tomada en cada versión liberada.

Los estados de liberación y el sucesor

El sucesor es la parte más útil para quien adecúa código clásico. Aparece en el propio mensaje de sintaxis: leer la tabla T001 en código ABAP Cloud da "The use of Table T001 is not permitted. Use CDS Entity I_COMPANYCODE instead.". Un objeto puede tener más de un sucesor: la MARA tiene cinco (I_Product, I_ProductQM, I_ProductSales, I_ProductStorage_2 y I_ProductProcurement), y la elección depende de los campos que usa el programa.

Dónde consultar el estado de un objeto

• En ADT: la pestaña API State, en las propiedades del objeto, muestra el contrato, el estado, la visibilidad y el sucesor. Un árbol de repositorio con el filtro api: lista los objetos por contrato (por ejemplo api:USE_IN_KEY_USER_APPS).
• En el sistema: el programa ABAP_DOCU_RELEASED_APIS lista los objetos con contrato. La tabla ARS_W_API_STATE guarda una línea por objeto y por contrato, con las columnas USE_IN_SAP_CLOUD_PLATFORM y USE_IN_KEY_USER_APPS para la visibilidad.
• En el GitHub de SAP: el Cloudification Repository (SAP/abap-atc-cr-cv-s4hc) tiene un archivo por release con los objetos liberados, los no liberados y los sucesores. El archivo no incluye contrato ni visibilidad y solo lista lo que es visible para ABAP Cloud. Una CDS liberada solo para Key User no aparece en él: para Key User, la fuente es el propio sistema.

Liberar un objeto propio

La empresa puede liberar sus propios objetos en C0 (solo para Cloud Development) y en C1, con cualquiera de las visibilidades. La liberación se hace en ADT, en la pestaña API State o con el menú Change API State, y acompaña al objeto en la orden de transporte como un objeto propio (R3TR APIS). El comentario escrito en el asistente de liberación queda solo en el sistema de origen y no se transporta.

El uso más común es el wrapper: un objeto en ABAP estándar que usa algo no liberado y se expone en C1 para el código ABAP Cloud de otro componente. La liberación permite el uso, pero no cambia los hallazgos del propio objeto en Clean Core. Los detalles están en Componentes de software en ABAP Cloud: quién puede llamar a quién y en Wrapper en Clean Core: la deuda se concentra, no desaparece. La visibilidad para Key User, y lo que habilita, está en ABAP for Key Users: qué son los objetos de Key User y dónde entran en Clean Core.

Fuentes

• SAP Help, ABAP Keyword Documentation 7.58: ABAP Language Versions, Release Contracts and Released APIs, los glosarios de los contratos C0 a C4 y las C1 Contract Rules for API Providers (CDS, objetos ABAP y diccionario). La versión 7.57 de la misma página, para la comparación del C4.
• SAP Help, ABAP Development Tools User Guide: Released APIs, Releasing Development Objects, las páginas de cada contrato, Deprecation y Checking the Compatibility of Released APIs.
• SAP Help, SAP BTP ABAP Environment: Software Component Dependencies y API Release Framework.
• SAP, Cloudification Repository (GitHub SAP/abap-atc-cr-cv-s4hc).
• Consultas a la tabla ARS_W_API_STATE y pruebas de liberación en un SAP S/4HANA 2023 (SAP_BASIS 758).