Contratos de liberação de API: o que o C0, o C1, o C2, o C3 e o C4 garantem

"Use só API liberada" é a regra mais repetida do ABAP Cloud e do Clean Core. Mas liberada como, para quem e com que garantia? Um objeto da SAP pode estar liberado para o ABAP Cloud e não para os apps de Key User, ou o contrário. Pode estar liberado para uso remoto e não para uso no próprio sistema. E um objeto Z liberado pela empresa não tem a mesma proteção de um objeto liberado pela SAP. Tudo isso está no contrato de liberação.

O que é um contrato de liberação

Um contrato de liberação (release contract) é uma classificação que o dono de um objeto do repositório ABAP põe nele para declará-lo API. Ele tem duas partes:

• o contrato, que diz o que não pode mais mudar no objeto e para que tipo de uso ele serve;
• a visibilidade, que diz quais versões de linguagem podem usá-lo: ABAP for Cloud Development, ABAP for Key Users ou as duas.

Sem contrato, um objeto da SAP não pode ser usado por código ABAP Cloud nem por código de Key User. É o contrato que faz de uma tabela, CDS, classe ou função uma "API liberada".

Os cinco contratos

O C4 é o mais novo: aparece na documentação do ABAP 7.58 (S/4HANA 2023) e não na 7.57. Num S/4HANA 2023 (SP00) medido, só quatro objetos da SAP tinham C4. O C1 é, de longe, o mais comum: é ele que decide o que o código ABAP Cloud e o código de Key User podem usar.

Visibilidade: ABAP Cloud, Key User ou os dois

Só o C0 e o C1 têm visibilidade. No C1, as duas opções são:

As duas são independentes, e a diferença não é detalhe. Num S/4HANA 2023 (SP00) medido, os objetos da SAP liberados em C1 se dividiam assim:

Há mais objetos liberados só para Key User do que só para ABAP Cloud. Só entre as CDS, eram 3.429 só para Key User contra 1.031 só para Cloud. Uma CDS como I_BudgetEntryDocumentType pode ser lida por uma Custom CDS View, mas uma classe ABAP Cloud que tenta lê-la recebe "The use of CDS Entity ... is not permitted". Já os módulos de função liberados são sempre só para ABAP Cloud: a documentação diz que função não pode ser liberada para Key User.

A visibilidade é presa à versão de linguagem, não a um componente de software. Um objeto liberado para Cloud Development pode ser usado por qualquer código ABAP Cloud do sistema.

O que muda depois da liberação

Liberar é prometer estabilidade. As regras da SAP para o C1 dizem o que não pode mais mudar:

• CDS: não se tira campo, parâmetro nem associação a alvo liberado, e só se acrescentam campos que não são chave. Não se muda a caixa dos nomes nem o tratamento de mandante, e SELECT * implícito é proibido;
• classes e interfaces: a classe precisa ser final ou abstrata, com instanciação privada. Não se apaga método, não se muda de estático para instância nem se reduz a visibilidade. Parâmetro opcional novo é permitido, mas ele não pode virar obrigatório;
• módulos de função: os parâmetros não mudam, opcionais podem entrar e exceções novas não;
• dicionário: não se remove campo de estrutura ou tabela, e não se encurta domínio. Tipo de tabela não muda em nada;
• qualquer objeto C1: não pode ser apagado depois de liberado. O caminho é marcá-lo como obsoleto, com um sucessor.

O C2 acrescenta a proibição de alongar campos, e o C4 não permite mudança nenhuma.

Quem impede uma mudança incompatível

Aqui está o ponto que mais se confunde. Para os objetos da SAP, o cumprimento do contrato é verificado por checks especiais do ATC, dentro do processo de desenvolvimento da própria SAP, antes de cada entrega.

Para os objetos que a empresa libera, a proteção também é do ATC, e não da ativação. Os checks são dois:

• API_COMPATIBILITY (API Release: Compatibility of Released APIs), que compara o objeto com uma foto da API (snapshot) tirada antes, no app Manage API Snapshots, que existe também no S/4HANA on-premise. Sem a foto, ele não aponta nada;
• API_CONSISTENCY (API Release: Consistency of Released APIs), que confere as regras do contrato.

Num S/4HANA 2023 sem essa foto configurada, a ativação aceitou, num objeto Z liberado em C1:

• tirar um campo de uma CDS;
• apagar o único método público de uma classe;
• liberar uma classe CREATE PUBLIC, contra a regra da instanciação privada;
• tirar a visibilidade Key User de uma CDS já liberada.

Nenhuma dessas mudanças deu erro. Ou seja: o C1 num objeto Z é uma promessa de quem libera, e o sistema só a cobra se o ATC de compatibilidade estiver em uso. Quem libera objetos Z para outros times precisa de três coisas: um processo de aprovação, que a própria SAP recomenda, esses checks na variante do ATC e uma foto da API tirada a cada versão liberada.

Os estados de liberação e o sucessor

O sucessor é a parte mais útil para quem adequa código clássico. Ele aparece na própria mensagem de sintaxe: ler a tabela T001 em código ABAP Cloud dá "The use of Table T001 is not permitted. Use CDS Entity I_COMPANYCODE instead.". Um objeto pode ter mais de um sucessor: a MARA tem cinco (I_Product, I_ProductQM, I_ProductSales, I_ProductStorage_2 e I_ProductProcurement), e a escolha depende dos campos que o programa usa.

Onde consultar o estado de um objeto

• No ADT: a aba API State, nas propriedades do objeto, mostra contrato, estado, visibilidade e sucessor. Uma árvore de repositório com o filtro api: lista os objetos por contrato (por exemplo api:USE_IN_KEY_USER_APPS).
• No sistema: o programa ABAP_DOCU_RELEASED_APIS lista os objetos com contrato. A tabela ARS_W_API_STATE guarda uma linha por objeto e por contrato, com as colunas USE_IN_SAP_CLOUD_PLATFORM e USE_IN_KEY_USER_APPS para a visibilidade.
• No GitHub da SAP: o Cloudification Repository (SAP/abap-atc-cr-cv-s4hc) tem um arquivo por release com os objetos liberados, os não liberados e os sucessores. O arquivo não traz contrato nem visibilidade e só lista o que é visível para ABAP Cloud. Uma CDS liberada só para Key User não aparece nele: para Key User, a fonte é o próprio sistema.

Liberar um objeto próprio

A empresa pode liberar os próprios objetos em C0 (só para Cloud Development) e em C1, com qualquer das visibilidades. A liberação é feita no ADT, pela aba API State ou pelo menu Change API State, e segue o objeto na request de transporte como um objeto próprio (R3TR APIS). O comentário escrito no assistente de liberação fica só no sistema de origem e não é transportado.

O uso mais comum é o wrapper: um objeto em ABAP padrão que usa algo não liberado e se expõe em C1 para o código ABAP Cloud de outro componente. A liberação permite o uso, mas não muda as ocorrências do próprio objeto no Clean Core. Os detalhes estão em Componentes de software no ABAP Cloud: quem pode chamar quem e em Wrapper no Clean Core: o débito se concentra, não some. A visibilidade para Key User, e o que ela abre, está em ABAP for Key Users: o que são os objetos de Key User e onde eles entram no Clean Core.

Fontes

• SAP Help, ABAP Keyword Documentation 7.58: ABAP Language Versions, Release Contracts and Released APIs, os glossários dos contratos C0 a C4 e as C1 Contract Rules for API Providers (CDS, objetos ABAP e dicionário). A versão 7.57 da mesma página, para a comparação do C4.
• SAP Help, ABAP Development Tools User Guide: Released APIs, Releasing Development Objects, as páginas de cada contrato, Deprecation e Checking the Compatibility of Released APIs.
• SAP Help, SAP BTP ABAP Environment: Software Component Dependencies e API Release Framework.
• SAP, Cloudification Repository (GitHub SAP/abap-atc-cr-cv-s4hc).
• Consultas à tabela ARS_W_API_STATE e testes de liberação num SAP S/4HANA 2023 (SAP_BASIS 758).