☕ Um Café no Bellacosa Mainframe
Gostou do conteúdo? Ajude a manter o café quente, o COBOL compilando e o mainframe acordado. 😄
☕ Pague um café ao Bellacosa

Translate

Mostrar mensagens com a etiqueta OpenAPI. Mostrar todas as mensagens
Mostrar mensagens com a etiqueta OpenAPI. Mostrar todas as mensagens

quinta-feira, 6 de junho de 2024

Sherlock Holmes, COBOL e o Mistério da API que Entrou no CICS sem Conhecer COMMAREA

 

Bellacosa Mainframe e o zos connect

☕ Um Café no Bellacosa Mainframe

Sherlock Holmes, COBOL e o Mistério da API que Entrou no CICS sem Conhecer COMMAREA

🔎 z/OS Connect, REST, JSON, OpenAPI, CICS, IMS, Db2, segurança, modernização e o curioso caso em que Watson jurava que o legado precisava morrer — até Holmes encontrar uma porta chamada API

Londres, 221B Baker Street.

Chovia.

Naturalmente chovia.

Toda boa investigação envolvendo sistemas legados começa com chuva, café frio e alguém dizendo:

— Holmes, temos um problema grave.

Sherlock Holmes não levantou os olhos do terminal 3270.

— Grave, Watson?

— Gravíssimo. A diretoria descobriu APIs.

Holmes parou.

A sala ficou em silêncio.

Até o JES2 pareceu diminuir o número de mensagens no console.

Watson continuou:

— Agora querem modernizar tudo.

— Naturalmente.

— Disseram que temos de substituir o COBOL.

Holmes finalmente virou a cadeira.

— E qual é o problema do sistema atual?

Watson consultou as anotações.

— Processa milhões de transações por dia, roda há vinte anos, tem disponibilidade excelente, regras de negócio consolidadas, integração com CICS e Db2 e praticamente ninguém sabe exatamente tudo que ele faz.

Holmes acendeu imaginariamente seu cachimbo.

— Então, Watson, já temos nosso primeiro suspeito.

— O COBOL?

— Não. A palavra modernização.

E assim começa nossa investigação.

Porque uma das coisas mais interessantes sobre o IBM z/OS Connect é justamente esta: ele nos obriga a separar duas coisas que muita apresentação corporativa insiste em colocar dentro da mesma mala.

Modernizar não é necessariamente reescrever.

Às vezes o sistema já está fazendo exatamente aquilo que deveria fazer.

O problema é apenas que ninguém do lado de fora consegue conversar com ele usando as interfaces modernas que o restante da empresa adotou.

E é aí que entra o z/OS Connect.



O cadáver não estava morto

Vamos começar pelo mistério clássico.

Você possui um programa COBOL.

Algo parecido com isto:

IDENTIFICATION DIVISION.
PROGRAM-ID. CONSULTA-SALDO.

DATA DIVISION.

WORKING-STORAGE SECTION.

01 WS-CONTA       PIC 9(08).
01 WS-SALDO       PIC S9(11)V99 COMP-3.
01 WS-LIMITE      PIC S9(11)V99 COMP-3.
01 WS-STATUS      PIC X(01).

PROCEDURE DIVISION.

    PERFORM CONSULTAR-CONTA
    PERFORM CALCULAR-LIMITE
    PERFORM RETORNAR-DADOS
    GOBACK.

O programa funciona.

Ele talvez seja executado dentro do CICS.

Talvez consulte Db2.

Talvez utilize uma COMMAREA.

Talvez faça parte de uma transação que existe desde uma época em que telefone celular parecia um tijolo usado para ligar para Gordon Gekko.

Durante anos, o acesso era feito por uma aplicação 3270.

Algo como:

USUÁRIO
   |
   v
TERMINAL 3270
   |
   v
CICS
   |
   v
COBOL
   |
   v
Db2

Perfeito.

Até que chegou o aplicativo mobile.

O novo desenvolvedor pergunta:

— Qual endpoint devo chamar para consultar saldo?

O COBOLzeiro responde:

— Endpoint?

— Sim. Algo como:

GET /accounts/123456/balance

— Rapaz, eu tenho uma COMMAREA.

E os dois se observam como arqueólogos de civilizações diferentes.

É exatamente esse tipo de fronteira tecnológica que o z/OS Connect ajuda a resolver.


A primeira pista: o que é z/OS Connect?

Em termos simples, o IBM z/OS Connect permite conectar recursos do z/OS ao universo de APIs.

Isso significa criar uma ponte entre tecnologias como:

COBOL
CICS
IMS
Db2
z/OS

e o universo:

HTTP
REST
JSON
OpenAPI
OAuth
JWT
Cloud
Mobile
Web
Kubernetes

Visualmente:

Aplicação Web
     |
Aplicação Mobile
     |
Microsserviço
     |
Sistema Cloud
     |
     v
 REST / JSON
     |
     v
+----------------+
| z/OS Connect   |
+----------------+
     |
     +------ CICS
     |
     +------ IMS
     |
     +------ aplicações z/OS
     |
     v
   COBOL
     |
     v
    Db2

Para Sherlock Holmes, isso seria a primeira evidência importante.

O COBOL não desapareceu.

Apenas ganhou um intérprete na porta.


Watson comete o primeiro erro: “Então z/OS Connect é um API Gateway?”

Não exatamente.

Esse é um daqueles erros suficientemente próximos da verdade para parecer corretos.

O z/OS Connect possui funções relacionadas a APIs, segurança e integração, mas sua função mais importante deve ser entendida como:

ligar APIs ao mundo z/OS.

Em uma arquitetura corporativa real, pode existir algo assim:

Internet
   |
   v
API Gateway corporativo
   |
   v
z/OS Connect
   |
   v
CICS
   |
   v
COBOL

O API Gateway pode cuidar de coisas como:

  • exposição externa;

  • políticas corporativas;

  • rate limiting;

  • analytics;

  • controle de consumidores;

  • roteamento;

  • autenticação de borda.

Enquanto o z/OS Connect trabalha próximo dos recursos do IBM Z.

Holmes provavelmente diria:

“Não confunda o mordomo com a porta da mansão, Watson. Ambos controlam quem entra, mas desempenham funções diferentes.”


API Provider: quando o mainframe oferece um serviço

Agora entramos em uma das funções mais importantes.

Imagine um CICS contendo transações como:

INQC  Consulta Cliente
INQS  Consulta Saldo
BLKC  Bloqueia Cartão
LIMC  Consulta Limite

No mundo antigo, uma aplicação talvez precisasse conhecer detalhes específicos do backend.

No mundo das APIs, podemos criar algo mais amigável:

GET /clientes/{id}

GET /contas/{id}/saldo

POST /cartoes/{id}/bloqueio

GET /cartoes/{id}/limite

Uma aplicação mobile poderia executar:

GET /contas/778899/saldo

E receber:

{
  "conta": "778899",
  "saldo": 28453.72,
  "moeda": "BRL"
}

Por trás disso:

Mobile
  |
  | HTTPS
  v
z/OS Connect
  |
  v
CICS
  |
  v
COBOL
  |
  v
Db2

A parte fascinante é esta:

o aplicativo não precisa saber que existe CICS.

E o COBOL não precisa saber que existe smartphone.

Cada lado trabalha dentro de seu próprio universo tecnológico.

Esse desacoplamento é uma das grandes virtudes da arquitetura.


Uma COMMAREA entra em Baker Street

Watson recebe uma estrutura COBOL:

01 DFHCOMMAREA.

   05 CA-ACCOUNT     PIC 9(08).
   05 CA-CUSTOMER    PIC X(40).
   05 CA-BALANCE     PIC S9(11)V99 COMP-3.
   05 CA-LIMIT       PIC S9(11)V99 COMP-3.
   05 CA-STATUS      PIC X(01).

Do outro lado chega:

{
  "account": "12345678"
}

Watson pergunta:

— Holmes, como esse JSON vai entrar nessa estrutura?

Holmes aponta para o quadro.

É justamente aqui que entra o conceito de mapeamento e transformação de dados.

Porque os dois mundos possuem representações diferentes.

JSON entende coisas como:

string
number
boolean
array
object
null

COBOL possui:

PIC X
PIC 9
COMP
COMP-3
OCCURS
REDEFINES
SIGN

Imagine:

05 BALANCE PIC S9(11)V99 COMP-3.

Isso não é simplesmente “um número”.

Existe representação interna.

Existe sinal.

Existe escala decimal.

Existe formato binário ou decimal compactado dependendo da declaração.

Portanto, converter:

{
  "balance": 1500.75
}

para uma estrutura COBOL envolve entender tipos e representação.

Não é magia.

É integração.


Easter egg nº 1: COMP-3 continua assustando quem vem da web

Um desenvolvedor JavaScript olha:

PIC S9(09)V99 COMP-3

e talvez pense:

“Por que o número está vestido de hieróglifo?”

O programador COBOL olha:

const value = data?.customer?.accounts?.[0]?.balance ?? 0;

e pensa exatamente a mesma coisa.

Cada geração cria sua própria magia negra.


OpenAPI: a ficha policial da API

Sherlock Holmes gostava de arquivos.

Dossiês.

Registros.

Descrições precisas.

OpenAPI provavelmente seria uma de suas tecnologias favoritas.

OpenAPI é uma especificação para descrever APIs HTTP.

Por exemplo:

paths:

  /accounts/{accountId}/balance:

    get:

      summary: Returns account balance

      parameters:

        - name: accountId
          in: path
          required: true

      responses:

        '200':
          description: Account found

        '404':
          description: Account not found

Esse arquivo pode descrever:

  • endpoints;

  • parâmetros;

  • métodos HTTP;

  • request;

  • response;

  • códigos de retorno;

  • schemas;

  • tipos de dados.

Para um programador COBOL iniciante, podemos fazer uma analogia.

Uma copybook define:

estrutura de dados

OpenAPI define:

estrutura da conversa.

A copybook responde:

“Como os dados estão organizados?”

OpenAPI responde:

“Como alguém chama esse serviço e o que ele recebe de volta?”

Não são equivalentes.

Mas ambos cumprem a função importantíssima de estabelecer contratos.


API-first: Holmes começa pela pergunta correta

Durante muitos anos, projetos de integração começavam assim:

Temos o programa ABC123. Como transformamos isso em uma API?

Funciona.

Mas arquiteturas modernas cada vez mais preferem começar de outra maneira:

Qual serviço o negócio precisa?

Imagine que precisamos oferecer consulta de saldo.

Primeiro definimos:

GET /accounts/{id}/balance

Depois definimos o retorno:

{
   "account": "123456",
   "availableBalance": 1800.42,
   "currency": "BRL"
}

Só depois perguntamos:

Quem implementará isso?

Talvez:

CICS + COBOL

Talvez:

IMS

Talvez:

Db2

Talvez daqui a dez anos:

outra implementação.

O consumidor não precisa necessariamente saber.

Este é o poder de um contrato bem definido.


O grande mistério: modernização sem reescrita

Aqui chegamos ao coração do caso.

Considere um programa COBOL com:

25 anos de produção

4.000 regras de negócio

dezenas de integrações

tratamentos de exceção

rotinas fiscais

regras contábeis

auditoria

segurança

controle transacional

Alguém entra em uma reunião e diz:

— Precisamos reescrever porque é legado.

Holmes pergunta:

— O sistema está errado?

— Não.

— Está lento?

— Não.

— É instável?

— Não.

— Não suporta o volume?

— Suporta.

— Então por que reescrever?

— Porque não é moderno.

Silêncio.

Esse é exatamente o ponto no qual tecnologias como z/OS Connect ficam interessantes.

Talvez você não precise substituir:

COBOL

Talvez precise substituir:

a maneira como os consumidores acessam o COBOL.

Veja a diferença:

ANTES

3270
 |
 v
CICS
 |
 v
COBOL

Depois:

Mobile
Web
Cloud
Parceiro
Kubernetes
    |
    v
REST API
    |
    v
z/OS Connect
    |
    v
CICS
    |
    v
COBOL

A lógica continua funcionando.

A interface muda.

Isso é modernização por integração.


Mas Holmes encontra pegadas indo na direção contrária

Até agora falamos de aplicações externas chamando o mainframe.

Mas existe outro cenário.

O próprio z/OS pode precisar chamar APIs externas.

Imagine um programa COBOL processando uma transação de cartão.

Ele precisa consultar um sistema antifraude baseado em IA rodando em cloud.

Fluxo:

CICS
 |
 v
COBOL
 |
 v
Integração API
 |
 v
Serviço antifraude
 |
 v
Cloud

Pergunta:

Mainframe pode consumir APIs modernas?

Sim.

Isso quebra uma imagem antiga do mainframe como uma fortaleza completamente isolada.

Na realidade, ambientes modernos são híbridos.

Algo como:

                CLOUD

         +------------------+
         | Fraud Detection  |
         +--------+---------+
                  ^
                  |
                REST
                  |
                  |
+----------------------------------+
|              IBM Z               |
|                                  |
|     COBOL ---- z/OS Connect      |
|       |                          |
|      CICS                        |
|       |                          |
|      Db2                         |
+----------------------------------+

Isso permite ao legado participar de ecossistemas modernos sem abandonar tudo aquilo que já faz bem.


Um pequeno caso para Watson investigar

Imagine uma transferência bancária.

O fluxo COBOL tradicional:

1. Validar conta de origem
2. Validar conta destino
3. Verificar saldo
4. Verificar limite
5. Executar débito
6. Executar crédito
7. Registrar auditoria

Agora surge uma nova regra:

Consultar sistema externo antifraude.

O programa pode enviar dados como:

{
  "customer": "823718",
  "amount": 12500.00,
  "destination": "998812",
  "channel": "MOBILE"
}

e receber:

{
  "riskScore": 87,
  "decision": "REVIEW"
}

O COBOL pode então continuar seu processamento.

Note o fenômeno.

O sistema não foi substituído.

Ele foi enriquecido por integração.


Segurança: Moriarty encontra a API

Toda vez que você cria uma nova interface, cria também uma nova superfície de ataque.

Moriarty ficaria muito interessado.

Imagine esta API:

POST /payments

Excelente.

Agora imagine que qualquer pessoa possa chamá-la.

Péssimo.

Logo entram conceitos como:

TLS
OAuth
JWT
autenticação
autorização
identidade
RACF
logging
auditoria
políticas

Uma arquitetura simplificada:

Aplicação
   |
   | token
   v
API Gateway
   |
   v
z/OS Connect
   |
   v
Segurança z/OS
   |
   v
CICS
   |
   v
COBOL

A pergunta crítica deixa de ser apenas:

“A API funciona?”

e passa a incluir:

“Quem chamou?”

“Com qual identidade?”

“Qual recurso tentou acessar?”

“Estava autorizado?”

“O que foi executado?”

“Existe trilha de auditoria?”

Para quem já conhece RACF, a filosofia não é estranha.

RACF sempre quis saber:

USER
RESOURCE
ACCESS

APIs simplesmente ampliam esse problema para um novo universo.


Easter egg nº 2: Sherlock provavelmente seria sysprog

Holmes observa detalhes insignificantes para inferir causas complexas.

Um sysprog vê:

IEC141I

e começa a reconstruir mentalmente meia hora de atividade no sistema.

Watson vê apenas:

“Deu erro.”

Holmes vê:

dataset, volume, catalog, disposition, job, step, allocation, contexto.

A diferença entre novato e veterano frequentemente não é conhecer mais comandos.

É reconhecer padrões.

Sherlock Holmes seria absolutamente perigoso com acesso ao SDSF.


A armadilha do “REST em tudo”

Agora vem um dos pontos mais importantes.

APIs são ferramentas.

Não religião.

Imagine um batch processando:

10.000.000 registros

localmente.

Alguém decide modernizar:

Cada registro chamará uma REST API.

Então você substitui:

10 milhões de operações locais

por:

10 milhões de chamadas HTTP.

Agora adicionamos:

rede
TLS
serialização
desserialização
timeouts
retries
latência
conexões
rate limits
monitoramento distribuído

Watson exclama:

— Mas ficou moderno!

Holmes responde:

— E quarenta vezes mais lento.

Nem toda chamada deve virar API.

Existem cenários em que:

CALL
LINK
MQ
batch
arquivo
Db2

continuam sendo alternativas perfeitamente adequadas.

Arquitetura madura não pergunta:

“Qual tecnologia está na moda?”

Ela pergunta:

“Qual mecanismo resolve melhor este problema?”


Granularidade: o caso das 47 APIs

Imagine um aplicativo bancário mostrando a página inicial.

Ele precisa de:

nome
saldo
limite
cartões
investimentos
últimas transações
empréstimos
mensagens

O arquiteto mais empolgado cria:

GET /customer
GET /balance
GET /limit
GET /cards
GET /investments
GET /transaction1
GET /transaction2
GET /transaction3
GET /loan
GET /messages

A tela abre.

E dispara uma pequena invasão contra o próprio mainframe.

Mobile
 |
 |--> API
 |--> API
 |--> API
 |--> API
 |--> API
 |--> API
 |--> API
 |--> API
 |
 v
z/OS

Isso pode gerar problemas de:

  • volume;

  • latência;

  • CPU;

  • conexão;

  • dependências;

  • falhas parciais;

  • escalabilidade.

Holmes diria:

“O fato de haver quarenta pegadas não significa que quarenta pessoas passaram pela sala. Talvez Watson tenha caminhado em círculos.”

Em APIs também.

Precisamos analisar granularidade.

Talvez a tela precise de uma API agregadora:

GET /customer-home

que retorne várias informações em uma chamada.

Não existe resposta universal.

Existe engenharia.


Observabilidade: onde estão escondidos os 4 segundos?

No velho ambiente:

CICS
 |
COBOL
 |
Db2

Se algo demorava, você analisava:

CICS statistics
SMF
RMF
Db2
CPU
I/O
locks
waits

Agora temos:

Smartphone
    |
Internet
    |
API Gateway
    |
z/OS Connect
    |
CICS
    |
COBOL
    |
Db2

Usuário reclama:

“Consulta demorou quatro segundos.”

Watson aponta para COBOL.

Holmes pergunta:

— Por quê?

— Porque é legado.

— Evidência?

— Nenhuma.

Então começa a investigação.

Talvez:

Mobile             150 ms
Internet           420 ms
Gateway             30 ms
z/OS Connect        40 ms
CICS                 4 ms
COBOL                7 ms
Db2                  5 ms
serviço externo   3100 ms

Resultado:

COBOL estava inocente.

Esse tipo de ambiente exige observabilidade ponta a ponta.

Você precisa conseguir seguir a transação desde a origem até o backend.


Kubernetes entra pela janela

Agora podemos ligar z/OS Connect ao mundo cloud-native.

Imagine:

+--------------------------------+
| Kubernetes                     |
|                                |
| Pod                            |
|   Spring Boot                  |
|                                |
+-------------+------------------+
              |
              | REST
              v
        z/OS Connect
              |
              v
            CICS
              |
              v
            COBOL
              |
              v
             Db2

Isso não é contradição.

É arquitetura híbrida.

Durante anos venderam uma falsa escolha:

MAINFRAME OU CLOUD

Na prática, muitas organizações operam:

MAINFRAME E CLOUD.

Cada plataforma resolve determinado conjunto de problemas.

Kubernetes pode executar:

frontends
microsserviços
APIs
workers
integrações
serviços stateless

IBM Z pode continuar executando:

core banking
pagamentos
contabilidade
CICS
IMS
Db2
batch crítico
regras centrais

APIs conectam os dois universos.


O mistério dos microsserviços

Watson encontra uma API REST.

— Holmes! Descobri um microsserviço!

Holmes olha para o backend:

REST
 |
 v
z/OS Connect
 |
 v
Programa COBOL de 400 mil linhas

— Não, Watson.

REST não significa automaticamente microsserviço.

Um monólito pode expor APIs.

Um microsserviço pode nem sequer usar REST.

Arquitetura de microsserviços envolve características como:

  • autonomia;

  • limites funcionais;

  • implantação independente;

  • ownership;

  • domínio;

  • resiliência;

  • governança distribuída.

Colocar:

/api

na frente de uma aplicação não transforma automaticamente sua arquitetura.

E isso nem sempre é problema.

Monólitos bem estruturados podem ser excelentes.

A pergunta deveria ser:

O sistema atende adequadamente os requisitos?

Não:

Ele parece suficientemente moderno numa apresentação?


Passo a passo mental para estudar z/OS Connect

Agora vamos montar o nosso roteiro de investigador.

Sempre que você olhar uma arquitetura, comece identificando cinco personagens.

1. Quem chama?

Pode ser:

Mobile
Web
Java
Python
Node.js
Kubernetes
Parceiro
SaaS
COBOL

Esse é o consumer.


2. Qual é a API?

Pergunte:

Qual endpoint?
Qual método?
Qual request?
Qual response?
Qual autenticação?

Exemplo:

GET /accounts/{id}/balance

3. Quem executa a regra real?

Pode ser:

CICS
IMS
COBOL
Db2
outra aplicação z/OS

Esse é o backend.


4. Como os dados são transformados?

Exemplo:

JSON
 |
 v
accountId = "123456"
 |
 v
estrutura COBOL
 |
 v
PIC 9(06)

E no retorno:

COMP-3
 |
 v
transformação
 |
 v
JSON number

5. Como a identidade atravessa o caminho?

Pergunte:

Quem é o usuário?
Qual token?
Qual credencial?
Como chega ao z/OS?
Qual autorização existe?

6. Como diagnostico problemas?

Pergunte:

Onde vejo logs?
Como correlaciono chamadas?
Como meço latência?
Como encontro falhas?
Como identifico backend lento?

Se você consegue responder essas seis perguntas, já deixou de apenas “usar uma ferramenta”.

Começou a entender arquitetura.


Exemplo completo: o caso da conta desaparecida

Recebemos uma chamada:

GET /accounts/123456/balance

O consumidor espera:

{
  "balance": 4200.75
}

Fluxo:

Mobile
 |
 v
API Gateway
 |
 v
z/OS Connect
 |
 v
CICS transaction
 |
 v
COBOL
 |
 v
Db2

COBOL executa:

EXEC SQL
   SELECT BALANCE
     INTO :WS-BALANCE
     FROM ACCOUNT
    WHERE ACCOUNT_ID = :WS-ACCOUNT-ID
END-EXEC.

Agora imagine:

SQLCODE = +100

Não encontrado.

No velho mundo, talvez você apresentasse:

ACCOUNT NOT FOUND

No mundo HTTP, podemos mapear semanticamente para:

HTTP 404

com:

{
  "error": "ACCOUNT_NOT_FOUND"
}

Observe novamente a tradução de paradigmas.

Db2 fala:

SQLCODE +100

CICS/COBOL entende sua lógica.

HTTP fala:

404

O consumidor moderno entende JSON.

O papel da arquitetura é fazer esses mundos conversarem sem destruir as características de cada um.


Curiosidade: interfaces mudam muito mais rápido que regras de negócio

Isso explica por que sistemas legados permanecem durante décadas.

Imagine uma regra:

SE SALDO + LIMITE >= VALOR
   AUTORIZAR TRANSAÇÃO

Ela pode existir desde 1995.

Enquanto a interface já passou por:

terminal
cliente-servidor
web
SOAP
mobile
REST
app
cloud

A regra mudou pouco.

A interface mudou seis vezes.

Isso explica uma ideia importantíssima em arquitetura:

isole aquilo que muda daquilo que permanece.

z/OS Connect ajuda justamente a separar:

regra central

de:

forma de acesso.

O antipadrão mais perigoso: API arqueológica

Imagine simplesmente pegar todas as transações antigas e expô-las diretamente:

TRN1 -> /trn1
TRN2 -> /trn2
TRN3 -> /trn3
TRN4 -> /trn4

Tecnicamente funciona.

Arquiteturalmente talvez seja um desastre.

Uma API deveria representar conceitos compreensíveis para consumidores.

Prefira coisas como:

/accounts
/customers
/payments
/cards

em vez de simplesmente publicar detalhes internos do CICS.

Porque se a API refletir profundamente a implementação interna, você cria acoplamento.

E então a suposta modernização apenas colocou JSON sobre a arquitetura antiga.

Holmes chamaria isso de:

o velho suspeito usando bigode falso.


Performance não desaparece porque usamos JSON

Outro erro comum é imaginar que APIs tornam performance um problema “do middleware”.

Não.

Cada request possui custo.

Podemos imaginar:

tempo total =
rede
+ TLS
+ gateway
+ processamento z/OS Connect
+ chamada CICS
+ execução COBOL
+ Db2
+ serialização
+ retorno

Se sua aplicação gerar:

20 requests

para cada usuário, e houver:

100.000 usuários simultâneos

a matemática rapidamente fica interessante.

Portanto, pense sempre em:

TPS
latência
concorrência
payload
CPU
conexões
timeouts
retries

O famoso velho mainframe continua cobrando aluguel por ciclo de CPU. 😄


Retry: o pequeno detalhe que pode duplicar dinheiro

Imagine:

POST /payments

O cliente envia uma transferência.

O backend processa.

Mas a resposta HTTP se perde.

O consumidor pensa:

Não funcionou.

Então faz retry.

Se o design não for cuidadoso, você pode executar a transferência duas vezes.

Por isso APIs transacionais precisam pensar em conceitos como:

idempotência
transaction IDs
correlation IDs
controle de duplicidade

Exemplo:

X-Transaction-ID: ABC123XYZ

O backend pode registrar:

ABC123XYZ já processada.

Isso é um excelente exemplo de como integração aparentemente simples toca profundamente em engenharia transacional.

O programador CICS veterano provavelmente sorrirá:

“Vocês acabaram de redescobrir problemas que resolvemos há quarenta anos.”

Sim.

Cloud-native frequentemente descobre que o velho mainframe já conhecia alguns monstros.

Apenas lhes dava outros nomes.


Easter egg nº 3: “Elementary, my dear Watson”

A frase mais associada a Sherlock Holmes:

“Elementary, my dear Watson.”

Curiosamente não aparece exatamente dessa forma nos contos originais de Arthur Conan Doyle.

É uma construção popularizada posteriormente.

Isso combina perfeitamente com tecnologia.

Várias “verdades históricas” de TI também se repetem até parecerem fatos:

Mainframe vai acabar.

COBOL vai desaparecer.

Batch é ultrapassado.

Tudo será cloud.

Tudo será microsserviço.

Décadas passam.

O mainframe continua processando.

COBOL continua executando.

Batch continua fechando o dia.

E alguém coloca Kubernetes na frente de tudo.


z/OS Connect como tradutor entre gerações

Talvez esta seja a melhor forma de compreender a tecnologia.

Imagine três gerações.

Geração 1

3270
CICS
COBOL
VSAM
Db2

Geração 2

Java
Web
SOAP
Application Servers

Geração 3

REST
JSON
OpenAPI
Cloud
Kubernetes
Mobile

Uma empresa raramente substitui uma geração inteira pela seguinte.

Ela acumula camadas.

Logo temos:

Mobile
   |
Cloud
   |
REST
   |
z/OS Connect
   |
CICS
   |
COBOL
   |
Db2

E isso não é necessariamente feio.

Pode ser exatamente a arquitetura apropriada.


A grande lição para o programador COBOL iniciante

Se você está começando agora em COBOL, existe uma tentação perigosa.

Pensar:

Preciso aprender apenas COBOL.

Não.

Aprenda COBOL profundamente.

Mas aprenda também o mundo ao redor.

Entenda:

HTTP
REST
JSON
OpenAPI
APIs
TLS
OAuth
JWT
CICS
Db2
MQ
Git
CI/CD
containers
Kubernetes

Você não precisa se transformar em especialista em tudo.

Mas precisa entender como essas peças se encaixam.

Porque o profissional COBOL mais valioso não será necessariamente aquele que memoriza mais verbos da linguagem.

Será aquele que consegue olhar:

React
 |
API
 |
z/OS Connect
 |
CICS
 |
COBOL
 |
Db2

e compreender a transação inteira.

Esse profissional consegue conversar com:

dev web
arquiteto
sysprog
DBA
segurança
cloud
CICS admin
negócio

Ele se torna uma ponte humana entre tecnologias.

E pontes são valiosas quando existem dois mundos que precisam conversar.


O último diálogo em Baker Street

Watson fecha o notebook.

— Então conseguimos transformar nosso sistema COBOL em um sistema moderno?

Holmes balança a cabeça.

— Não exatamente.

— Não?

— O sistema já era moderno para o problema que resolvia.

Watson franze a testa.

Holmes continua:

— Apenas ensinamos o resto do mundo a conversar com ele.

No monitor aparece:

GET /accounts/123456/balance

A chamada atravessa HTTPS.

Passa pela camada de APIs.

Chega ao z/OS Connect.

Entra no CICS.

Executa COBOL.

Consulta Db2.

Volta.

{
  "balance": 7250.00
}

O smartphone exibe:

Saldo disponível: R$ 7.250,00

Em algum lugar abaixo de milhares de camadas de software, um programa COBOL executa:

MOVE WS-SALDO TO CA-SALDO.

Ninguém no celular sabe.

Ninguém precisa saber.

Holmes sorri.

— Elementary, Watson.

— O quê?

— Modernização não significa demolir a mansão.

Holmes aponta para a tela.

— Às vezes basta instalar uma porta nova.

E talvez essa seja a melhor definição informal de z/OS Connect para quem vem do mundo COBOL:

uma porta moderna instalada em uma casa que continua sendo extraordinariamente boa em guardar as coisas mais valiosas da empresa.

No mundo do Bellacosa Mainframe, Watson finalmente aprende a regra:

LEGADO + API != LEGADO DISFARÇADO

LEGADO + BOA ARQUITETURA
        =
CAPACIDADE REUTILIZADA

E quando algum consultor aparecer dizendo:

“Precisamos reescrever tudo.”

Não discuta.

Pegue a lupa.

Pergunte:

Qual é o problema real?

É a regra?

É a plataforma?

É a interface?

É a integração?

É performance?

É custo?

É competência?

Ou alguém simplesmente confundiu
idade com obsolescência?

Sherlock Holmes aprovaria.

O velho sysprog também.

E o COBOL?

O COBOL continuará rodando enquanto todos terminam a reunião.

☕🔎🖥️

sexta-feira, 8 de dezembro de 2023

24 Horas no Bellacosa Mainframe: Jack Bauer, COBOL e a API que precisava entrar no CICS antes que o relógio chegasse a zero graças ao Zos Connect

 

Bellacosa Mainframe e o zos connect

☕ Um Café no Bellacosa Mainframe

24 Horas no Bellacosa Mainframe: Jack Bauer, COBOL e a API que precisava entrar no CICS antes que o relógio chegasse a zero

⏱️ z/OS Connect, REST, JSON, OpenAPI, CICS, IMS, Db2, RACF, SAF, zIIP, OpenTelemetry e o estranho caso em que Jack Bauer descobriu que reescrever 35 anos de COBOL levaria um pouco mais de 24 horas

03:17:42

O telefone toca.

Isso nunca é bom.

Especialmente quando você trabalha com mainframe.

Do outro lado da linha alguém pronuncia aquelas palavras capazes de provocar mais medo em um programador COBOL do que S0C7, SOC4, deadlock no Db2 e café descafeinado juntos:

— Precisamos modernizar o legado.

Silêncio.

O relógio aparece na tela.

03:17:43
03:17:44
03:17:45

Você olha para o terminal 3270.

O CICS está funcionando.

O Db2 está funcionando.

O programa COBOL que consulta clientes está funcionando há décadas.

Milhões de transações passaram por ele.

Então surge a pergunta que deveria ser feita antes de qualquer projeto de modernização:

Se funciona, por que exatamente queremos reescrevê-lo?

Do outro lado alguém responde:

— Porque precisamos acessar isso pelo aplicativo mobile.

Jack Bauer entra na sala.

Olha para o COBOL.

Olha para o arquiteto.

Olha para o relógio.

E diz:

— Então vocês não precisam reescrever o COBOL. Precisam de uma API.

TIC. TIC. TIC. TIC.

Bem-vindo ao mundo do IBM z/OS Connect.

Pegue o café.

Temos 24 horas para colocar REST, JSON e OpenAPI diante de um programa COBOL que nasceu quando ninguém imaginava que um telefone serviria para fazer transferências bancárias.


⏱️ 04:00 — O problema nunca foi necessariamente o COBOL

Imagine que nosso banco fictício possui um programa chamado:

CLIENTE

Ele recebe:

01 CLIENTE-REQUEST.
   05 CLIENTE-ID       PIC 9(09).

E devolve:

01 CLIENTE-RESPONSE.
   05 CLIENTE-NOME     PIC X(40).
   05 CLIENTE-LIMITE   PIC 9(09)V99.
   05 CLIENTE-STATUS   PIC X(01).

Nada particularmente revolucionário.

Talvez esse programa execute dentro do CICS e consulte Db2.

Durante décadas alguma aplicação tradicional soube perfeitamente como conversar com ele.

Então chega uma equipe responsável pelo novo aplicativo mobile.

Ela não sabe o que é:

COMMAREA
EBCDIC
PIC X
PIC 9
COMP
COMP-3
EXEC CICS LINK
TSO
ISPF
3270

E existe uma boa notícia:

ela provavelmente não precisa saber.

A aplicação mobile quer algo como:

GET /clientes/123456789

e espera receber:

{
  "id": 123456789,
  "nome": "JOAO DA SILVA",
  "limite": 15000.00,
  "status": "ATIVO"
}

Aqui aparece o problema arquitetural.

Não temos necessariamente um sistema antigo incapaz de executar a regra de negócio.

Temos dois mundos falando idiomas diferentes.

De um lado:

HTTP
REST
JSON
OpenAPI
OAuth
JWT
Cloud
Mobile
Microservices

Do outro:

COBOL
CICS
IMS
Db2
copybooks
SAF
RACF

Jack Bauer olha para os dois lados.

— Precisamos de um tradutor.

É aqui que entra o IBM z/OS Connect.


⏱️ 05:00 — Afinal, o que diabos é z/OS Connect?

Para um COBOLzeiro começando agora, eu gosto desta definição:

IBM z/OS Connect é uma camada de integração que permite disponibilizar recursos e aplicações do z/OS através de APIs REST e também permite que aplicações z/OS consumam APIs externas.

Leia novamente a última parte.

Porque ela é frequentemente esquecida.

Não existe apenas:

MUNDO MODERNO
      │
      ▼
     API
      │
      ▼
 MAINFRAME

Também pode existir:

 MAINFRAME
      │
      ▼
     API
      │
      ▼
MUNDO EXTERNO

Esses dois caminhos nos levam a dois conceitos fundamentais:

API PROVIDER
API REQUESTER

Guarde esses nomes.

Jack Bauer certamente guardaria.

Ele só não teria tempo de anotá-los.


⏱️ 06:00 — API Provider: quando o mundo bate à porta do CICS

O API Provider resolve aproximadamente este cenário:

Mobile
   │
Web
   │
Cloud
   │
   ▼
REST / JSON
   │
   ▼
z/OS Connect
   │
   ▼
CICS / IMS / Db2
   │
   ▼
COBOL

Imagine novamente nosso programa de consulta de clientes.

O aplicativo envia:

GET /clientes/123456789

z/OS Connect recebe essa requisição.

Ele possui informações suficientes para entender que aquela operação está relacionada a determinado serviço no mainframe.

O JSON pode ser transformado para a estrutura esperada pelo programa.

O programa COBOL executa.

Depois acontece o caminho inverso:

COBOL
   │
estrutura tradicional
   │
   ▼
z/OS Connect
   │
JSON
   ▼
aplicação

Perceba a beleza arquitetural.

O COBOL não precisa acordar numa segunda-feira e dizer:

“A partir de hoje sou desenvolvedor REST.”

Ele continua fazendo aquilo para o qual foi criado.


⏱️ 07:00 — Não estamos transformando COBOL em REST

Essa diferença parece pequena, mas é gigantesca.

Uma simplificação perigosa seria dizer:

COBOL → REST

Não.

O programa COBOL continua sendo COBOL.

Estamos criando uma interface moderna para uma capacidade existente.

Pense assim:

             CONTRATO
              OpenAPI
                 │
                 ▼
            REST / JSON
                 │
                 ▼
          z/OS Connect
                 │
        mapping / routing
                 │
                 ▼
        estrutura COBOL
                 │
                 ▼
              CICS
                 │
                 ▼
              COBOL

Isso nos leva a uma das ideias mais importantes deste café:

Modernização não significa necessariamente reescrita.

Às vezes modernizar significa tornar acessível aquilo que já funciona.


⏱️ 08:00 — A reunião em que alguém quer reescrever tudo

Você conhece a cena.

Sala de reunião.

PowerPoint.

Café ruim.

Alguém aponta para um desenho cheio de caixas coloridas e diz:

— Temos que eliminar o legado.

Pergunte:

— Por quê?

Talvez a resposta seja:

— Porque precisamos disponibilizar consulta de saldo no celular.

Mas o programa de consulta de saldo funciona?

— Sim.

Está performando?

— Sim.

É confiável?

— Sim.

Possui décadas de regras de negócio?

— Sim.

Então talvez o problema não seja:

CONSULTAR-SALDO

Talvez o problema seja somente:

COMO ACESSAR CONSULTAR-SALDO

São problemas completamente diferentes.

Reescrever pode ser necessário em alguns casos.

Mas não deveria ser automaticamente sinônimo de modernização.


⏱️ 09:00 — O tesouro escondido dentro daquele COBOL feio

Aqui mora uma coisa que os novatos precisam aprender cedo.

Você abre um programa de 15 mil linhas.

Encontra:

IF WS-CODIGO = 37
   AND WS-TIPO = 'X'
   AND WS-DATA < 19981231
      MOVE 'S' TO WS-EXCECAO
END-IF

Sua primeira reação pode ser:

— Que porcaria é essa?

Calma.

Talvez esse IF exista porque:

  • uma lei mudou;

  • houve uma fusão bancária;

  • determinado produto foi descontinuado;

  • aconteceu um incidente em produção;

  • alguma regra fiscal antiga precisa continuar sendo respeitada;

  • existem contratos históricos;

  • alguém descobriu uma exceção em 1999.

Código legado não contém apenas instruções.

Ele contém arqueologia empresarial.

Às vezes aquelas linhas horrorosas são conhecimento institucional fossilizado.

O perigo da reescrita é acreditar que compreendemos tudo simplesmente porque entendemos a sintaxe.


⏱️ 10:00 — OpenAPI entra na CTU

O próximo personagem da história é o OpenAPI.

Podemos pensar nele como um contrato descrevendo nossa API.

Por exemplo:

paths:
  /clientes/{id}:
    get:
      summary: Consulta cliente
      parameters:
        - name: id
          in: path
          required: true

Ele documenta coisas como:

endpoint
método HTTP
parâmetros
estrutura de entrada
estrutura de saída
códigos de resposta

Isso permite que diferentes equipes compartilhem um contrato comum.

O desenvolvedor mobile não precisa perguntar:

— Qual é o offset do campo CLIENTE-ID na COMMAREA?

Ele pergunta:

— Qual é o contrato da API?

Essa mudança cultural é enorme.


⏱️ 11:00 — O copybook encontra JSON

Agora chegamos a uma das partes mais interessantes.

No mainframe podemos encontrar:

01 CUSTOMER-DATA.
   05 CUSTOMER-ID      PIC 9(09).
   05 CUSTOMER-NAME    PIC X(40).
   05 CUSTOMER-BALANCE PIC S9(9)V99 COMP-3.

No universo web:

{
  "customerId": 12345,
  "customerName": "MARIA",
  "customerBalance": 3450.25
}

Veja o abismo cultural.

O frontend não quer saber que COMP-3 existe.

Aliás, se você explicar packed decimal durante a daily do React, talvez seja expulso da reunião.

O z/OS Connect pode participar justamente da transformação entre esses formatos.

Conceitualmente:

JSON
 ↓
mapping
 ↓
estrutura nativa
 ↓
COBOL
 ↓
estrutura nativa
 ↓
mapping
 ↓
JSON

E isso é maravilhoso porque preserva uma regra fundamental:

não obrigue todas as aplicações da empresa a conhecer os detalhes internos umas das outras.


⏱️ 12:00 — API Requester: plot twist!

Metade da temporada passou.

Hora da reviravolta.

Até agora o mundo estava chamando o mainframe.

Mas e se o COBOL precisar chamar o mundo?

Imagine um programa bancário precisando consultar uma cotação externa.

A API moderna oferece:

GET /exchange/USD/BRL

Resposta:

{
  "currency": "USD",
  "rate": 5.42
}

Agora temos:

COBOL
  │
  ▼
z/OS Connect
  │
  ▼
REST / JSON
  │
  ▼
API EXTERNA

É o API Requester.

Isso muda muito a percepção do mainframe.

Ele deixa de ser apenas:

“a máquina que os outros sistemas chamam”.

Também pode tornar-se consumidor de serviços modernos.


⏱️ 13:00 — Provider e Requester juntos

Agora nosso desenho fica muito mais interessante:

                    API PROVIDER

Mobile / Cloud ─── REST ───► z/OS Connect
                                  │
                                  ▼
                           CICS / IMS / Db2
                                  │
                                  ▼
                                COBOL
                                  │
                                  │
                           API REQUESTER
                                  │
                                  ▼
                              REST API
                                  │
                                  ▼
                         Serviço externo

Isso é integração bidirecional.

O mainframe deixa de parecer uma ilha.

Ele passa a participar da arquitetura distribuída da empresa.


⏱️ 14:00 — Mas espere: INTERNET → COBOL?

Jack Bauer para no corredor.

Olha para você.

— Você colocou a internet na frente da minha transação bancária?

Boa pergunta.

Porque API sem segurança é apenas uma maneira moderna de criar um incidente.

Aqui entram mecanismos como:

TLS
JWT
SAF
RACF
autenticação
autorização
controle por operação

A ideia não deveria ser:

INTERNET
   │
   ▼
COBOL

Mas algo conceitualmente muito mais parecido com:

REQUEST
   │
   ▼
TLS
   │
   ▼
AUTENTICAÇÃO
   │
   ▼
AUTORIZAÇÃO
   │
   ▼
z/OS Connect
   │
   ▼
SAF / RACF
   │
   ▼
RECURSO

O velho castelo ganhou uma porta moderna.

Não removemos os guardas.


⏱️ 15:00 — Autorização granular

Existe uma diferença importante entre:

VAGNER PODE ACESSAR A API

e:

VAGNER PODE EXECUTAR ESTA OPERAÇÃO?

Considere:

GET /contas/123

versus:

POST /transferencias

Consultar saldo e transferir dinheiro são operações completamente diferentes.

Em segurança empresarial queremos aproximar-nos do princípio:

least privilege

Ou seja:

conceder apenas aquilo que determinado usuário ou identidade realmente necessita.

Isso também mostra por que API modernization não é simplesmente instalar um servidor HTTP na LPAR e comemorar.

Existe arquitetura por trás.


⏱️ 16:00 — O telefone toca novamente

— Jack, a API está lenta.

Pronto.

Começou a produção.

Agora precisamos responder:

onde estão os 800 milissegundos?

Pode ser:

Mobile
  ↓
rede
  ↓
API Gateway
  ↓
z/OS Connect
  ↓
CICS
  ↓
COBOL
  ↓
Db2

Sem observabilidade, todos apontam para o vizinho.

O pessoal web:

— Mainframe está lento.

O mainframe:

— Aqui está normal.

A rede:

— Não é comigo.

O DBA:

— A query levou 2 ms.

E assim nasce uma war room de oito horas.


⏱️ 17:00 — OpenTelemetry encontra SMF

O universo moderno fala muito em:

metrics
logs
traces
OpenTelemetry
Prometheus
Grafana

O mainframe possui sua própria tradição de observabilidade:

SMF
RMF
CICS statistics
CICS monitoring
logs

z/OS Connect vive justamente numa região onde esses universos podem se encontrar.

E existe algo poeticamente maravilhoso nisso.

A turma cloud-native descobre distributed tracing.

O velho sysprog toma um gole de café e responde:

— Interessante. Nós também gostamos de saber para onde foi nosso CPU desde antes de você nascer.

Easter egg número 1: nunca diga a um sysprog veterano que observabilidade foi inventada junto com Kubernetes.

Você poderá assistir a uma palestra improvisada de quatro horas sobre SMF.


⏱️ 18:00 — E aquele papo de 99% no zIIP?

Aqui precisamos impedir um pequeno atentado conceitual.

Você poderá ler que mais de 99% do processamento relacionado ao z/OS Connect pode ser elegível para zIIP em determinadas condições de execução nativa.

Então alguém inevitavelmente concluirá:

“Excelente! 99% do meu COBOL vai para zIIP!”

NÃO.

Jack Bauer bate na mesa.

O relógio para durante dois segundos dramáticos.

A afirmação refere-se ao processamento do z/OS Connect, não magicamente a toda carga que existe atrás dele.

Pense:

HTTP processing
JSON transformation
z/OS Connect runtime
        │
        └────► alta elegibilidade zIIP

Depois:

CICS
COBOL
Db2
outros componentes

possuem suas próprias características e regras.

Esse detalhe é fundamental quando alguém começa a transformar arquitetura técnica em planilha financeira.


⏱️ 19:00 — Containers chegam ao mainframe

Outra surpresa para quem pensa que mainframe significa somente:

JCL + STARTED TASK + 3270

O ecossistema moderno do z/OS Connect também contempla deployment containerizado em cenários suportados.

Entram conceitos como:

OCI containers
OpenShift
z/OS Container Extensions
IBM Z

Ou seja, podemos encontrar arquiteturas muito diferentes.

Mas cuidado.

Não conclua:

“Então qualquer componente pode ser colocado em qualquer lugar.”

Características, features e restrições podem variar conforme o modelo de implantação e versão.

Regra do velho Bellacosa:

Antes de transformar um slide de arquitetura em implementação, leia a documentação da versão que realmente será instalada.

Essa frase evita mais incidentes que muita ferramenta cara.


⏱️ 20:00 — E IBM MQ?

Aqui mora outra armadilha interessante.

Em material introdutório é comum vermos juntos:

CICS
IMS
Db2
IBM MQ

Mas suporte depende da feature e geração utilizada.

O ecossistema histórico do z/OS Connect possui diferenças entre gerações e recursos.

Portanto:

“z/OS Connect suporta X” não é uma informação completa sem perguntar versão, feature e cenário.

Isso vale para MQ e praticamente qualquer produto empresarial com anos de evolução.

Easter egg número 2: em mainframe, a resposta para “isso é suportado?” frequentemente começa com:

“Depende do release.”

Se alguém responder imediatamente “sim” sem perguntar versão, comece a ficar desconfiado.


⏱️ 21:00 — API Management não é z/OS Connect

Outra confusão clássica.

Podemos ter:

CONSUMIDORES
     │
     ▼
API MANAGEMENT
     │
     ▼
z/OS Connect
     │
     ▼
CICS / IMS / Db2

API Management pode cuidar de coisas como:

catálogo
lifecycle
analytics
policies
plans
governança
consumidores

z/OS Connect possui foco específico na integração entre APIs e recursos z/OS.

São papéis complementares.

Pense num aeroporto.

API Management administra boa parte da relação com passageiros, rotas, regras e portas.

z/OS Connect é o intérprete altamente especializado que sabe conversar com aquela aeronave de 300 toneladas chamada CICS.


⏱️ 22:00 — Passo a passo mental para criar nossa API

Vamos montar uma operação conceitual.

Temos:

Programa: CLIENTE
Ambiente: CICS
Entrada: CLIENTE-ID
Saída:
   CLIENTE-NOME
   CLIENTE-LIMITE
   CLIENTE-STATUS

Passo 1 — Descubra a capacidade de negócio

Não comece pelo REST.

Pergunte:

O que esse programa realmente faz?

Resposta:

CONSULTAR CLIENTE

Passo 2 — Entenda entrada e saída

Localize copybooks e estruturas.

05 CLIENTE-ID PIC 9(09).

Saída:

05 CLIENTE-NOME   PIC X(40).
05 CLIENTE-LIMITE PIC 9(09)V99.
05 CLIENTE-STATUS PIC X.

Passo 3 — Pense na API como contrato

Por exemplo:

GET /clientes/{id}

Passo 4 — Defina representação externa

{
   "id": 123,
   "nome": "MARIA",
   "limite": 8000.00,
   "status": "ATIVO"
}

Passo 5 — Configure o mapping

Conceitualmente:

id
   ↕
CLIENTE-ID

nome
   ↕
CLIENTE-NOME

limite
   ↕
CLIENTE-LIMITE

Passo 6 — Configure segurança

Pergunte:

Quem chama?
Como autentica?
Qual identidade chega ao z/OS?
Qual operação pode executar?
Qual recurso SAF protege?

Passo 7 — Teste

Não teste somente:

HTTP 200

Teste também:

dados inválidos
cliente inexistente
timeout
indisponibilidade CICS
falha Db2
credencial inválida
usuário sem autorização
campos limites
concorrência
volume

Passo 8 — Observe

Descubra antes da produção:

latência
throughput
CPU
zIIP
erros
timeouts
dependências

Passo 9 — Documente

OpenAPI não deveria ser decoração.

É parte do contrato entre equipes.

Passo 10 — Só então coloque Jack Bauer de plantão

Preferencialmente não coloque.

Se precisarmos dele, alguma coisa já deu muito errado.


⏱️ 23:00 — O verdadeiro significado de modernização

Agora chegamos à parte que considero mais importante.

Existe uma narrativa confortável:

VELHO = RUIM
NOVO = BOM

Computação real não funciona assim.

Um programa COBOL criado em 1992 pode estar executando uma regra crítica perfeitamente.

Uma aplicação criada há seis meses em Kubernetes pode ser uma catástrofe arquitetural.

Idade não é qualidade.

Tecnologia nova não é automaticamente modernização.

A pergunta deveria ser:

Que problema de negócio estamos tentando resolver?

Se o problema for:

“Precisamos disponibilizar capacidades do mainframe para novos canais.”

Talvez a resposta seja integração.

Não reescrita.


⏱️ 23:42 — O castelo Bellacosa

Imagine o mainframe como um castelo gigantesco.

Dentro dele vivem:

COBOL
CICS
IMS
Db2
RACF
JES2

Durante décadas quem quisesse entrar precisava conhecer os costumes locais:

3270
TSO
ISPF
JCL
copybook
COMMAREA
EBCDIC

Então construímos uma recepção moderna.

Na porta está escrito:

HTTPS
REST
JSON
OpenAPI

O visitante chega.

— Quero consultar a conta 123.

Ele envia:

GET /accounts/123

A recepção entende.

Traduz.

Entra no castelo.

O velho COBOL recebe sua estrutura.

Executa.

Consulta Db2.

Devolve os dados.

A recepção traduz novamente.

O visitante recebe:

{
   "account": 123,
   "balance": 8542.71
}

E vai embora.

Ele nunca soube que CICS existia.

E o CICS nunca precisou aprender React.

Isso é desacoplamento.


⏱️ 23:50 — A curiosidade que muda tudo

Perceba uma consequência filosófica interessante.

Uma aplicação pode ter:

30 anos de idade

e possuir uma interface criada ontem.

Portanto:

A idade da implementação não determina a idade da interface.

Essa frase merece ficar colada perto do monitor.

Podemos ter:

React
   │
REST
   │
API Gateway
   │
z/OS Connect
   │
CICS
   │
COBOL
   │
Db2

Qual é a idade desse sistema?

2026?

2015?

2002?

1989?

A resposta correta talvez seja:

todas elas.

Sistemas empresariais são cidades.

Não são casas.

Uma cidade possui prédios de 1890, metrô de 1970, fibra óptica de 2025 e alguém pagando café pelo celular dentro de um edifício construído quando telefone ainda tinha fio.

Ninguém diz:

“Precisamos demolir Lisboa porque algumas construções são antigas.”

Integramos.

Restauramos.

Substituímos onde necessário.

Preservamos onde faz sentido.


⏱️ 23:55 — Cinco dicas do velho COBOLzeiro

Se você está começando em COBOL e z/OS Connect, guarde estas ideias.

1. Aprenda HTTP e REST.

Você não precisa virar desenvolvedor frontend, mas precisa entender:

GET
POST
PUT
DELETE
headers
status codes
JSON
TLS

2. Aprenda OpenAPI.

O contrato é parte central desse novo mundo.

3. Continue estudando COBOL profundamente.

API nenhuma elimina a necessidade de entender aquilo que existe atrás dela.

4. Aprenda segurança.

Especialmente:

SAF
RACF
TLS
JWT
identidade
autenticação
autorização
least privilege

5. Aprenda observabilidade.

Porque depois do primeiro:

HTTP 200 OK

virá inevitavelmente:

“Por que demorou 1,7 segundo?”

E alguém precisará descobrir.


⏱️ 23:58 — O último plot twist

Jack Bauer finalmente encontra o responsável pelo incidente.

Não era o COBOL.

Não era o CICS.

Não era o Db2.

Não era RACF.

Era uma aplicação distribuída fazendo 47 chamadas redundantes para a mesma API para montar uma única tela.

O sysprog olha para Jack.

Jack olha para o sysprog.

O sysprog pergunta:

— Quer café?

— Quanto tempo temos?

00:01:42

— Dá.


⏱️ 23:59 — O relógio chega ao fim

Agora podemos resumir toda nossa arquitetura:

                     IBM z/OS CONNECT
                            │
             ┌──────────────┴──────────────┐
             │                             │
             ▼                             ▼

        API PROVIDER                  API REQUESTER

      mundo → z/OS                   z/OS → mundo

       REST/JSON                         COBOL
           │                               │
           ▼                               ▼
     z/OS Connect                    z/OS Connect
           │                               │
           ▼                               ▼
   CICS / IMS / Db2                  REST APIs
           │                               │
           ▼                               ▼
         COBOL                       Cloud / SaaS

Ao redor disso existem:

OpenAPI
mapping
security
SAF
RACF
TLS
JWT
OpenTelemetry
SMF
zIIP
containers
OpenShift
API Management
DevOps

Mas existe uma ideia ainda maior envolvendo tudo isso:

MODERNIZAÇÃO
      │
      ▼
não significa obrigatoriamente
      │
      ▼
REESCRITA

Modernização pode significar:

PRESERVAR
    │
    ▼
CAPACIDADES DE NEGÓCIO
    │
    ▼
DESACOPLAR
    │
    ▼
EXPOR POR CONTRATOS MODERNOS
    │
    ▼
INTEGRAR
    │
    ▼
EVOLUIR

☕ Epílogo — 00:00:00

O relógio finalmente chega a zero.

A API está funcionando.

O aplicativo mobile consulta o cliente.

O request entra como REST.

z/OS Connect recebe JSON.

A estrutura chega ao CICS.

O programa COBOL executa.

Db2 responde.

A informação volta.

O usuário vê seu saldo no smartphone.

Ele toca na tela e reclama:

— Nossa, tecnologia moderna é incrível.

No datacenter, silenciosamente, um programa COBOL escrito quando Windows 3.1 era novidade acabou de fazer o trabalho pesado.

Ele não recebeu aplausos.

Não apareceu no aplicativo.

Ninguém colocou seu nome na keynote.

Ele simplesmente executou outra transação.

Como fez milhões de vezes.

Jack Bauer fecha o notebook.

O operador olha para a console.

CICS STATUS: ACTIVE

Tudo normal.

Então o velho COBOLzeiro toma o último gole de café e deixa uma anotação para o turno seguinte:

Não confundam modernização com demolição. Às vezes o sistema não precisa de um coração novo. Precisa apenas de uma porta nova.

Na porta está escrito:

REST
JSON
OpenAPI

Atrás dela continua existindo:

PROCEDURE DIVISION.

    PERFORM PROCESSAR-NEGOCIO.

    GOBACK.

00:00:01

O telefone toca novamente.

— Temos outro problema.

— Qual?

— Agora querem colocar IA acessando a API.

O COBOLzeiro olha para Jack Bauer.

Jack Bauer olha para o relógio.

O relógio começa novamente:

24:00:00
23:59:59
23:59:58...

E em algum lugar muito distante do CPD alguém abre um PowerPoint chamado:

AI MAINFRAME MODERNIZATION
FINAL_v7_REAL_FINAL_AGORA_VAI.pptx

O operador suspira.

— Passa o café.

Easter egg final: se você trabalha em TI há tempo suficiente, sabe que o arquivo FINAL_v7_REAL_FINAL_AGORA_VAI jamais é a versão final.

E talvez essa seja a única constante mais confiável que o próprio mainframe.

☕

sexta-feira, 3 de junho de 2022

⚔️ ITAMI E A DUNGEON DAS APIs — QUANDO O PROGRAMADOR COBOL DESCOBRIU QUE ENDPOINT NÃO ERA SÓ UMA URL

 

Bellacosa Mainframe entenda apis

☕ Um Café no Bellacosa Mainframe

⚔️ ITAMI E A DUNGEON DAS APIs — QUANDO O PROGRAMADOR COBOL DESCOBRIU QUE ENDPOINT NÃO ERA SÓ UMA URL

Endpoints, HTTP, REST, OAuth, tokens, idempotência, cache, rate limiting, webhooks, OpenAPI, API Gateway, microsserviços, agentes de IA — e o dia em que Youji Itami atravessou o GATE e descobriu que sistemas distribuídos também possuem monstros.



🎬 PRÓLOGO — ABRIU UM GATE NO DATACENTER

O programador COBOL olhou para o terminal 3270.

Tudo estava normal.

O programa compilava.

O CICS estava respondendo.

O Db2 continuava guardando dados importantes como fazia havia décadas.

O batch da madrugada havia terminado sem abend.

Até que Youji Itami, segundo-tenente da Força Terrestre de Autodefesa do Japão e veterano involuntário de situações absurdamente complicadas, apareceu carregando uma documentação de API.

— Temos um problema.

O programador olhou desconfiado.

— SOC7?

— Não.

— ASRA?

— Também não.

— SQLCODE -911?

— Pior.

Itami colocou sobre a mesa um desenho:

Mobile
   |
   v
API Gateway
   |
   +----------> Microservice
   |
   +----------> Cloud
   |
   +----------> AI Agent
   |
   +----------> z/OS Connect
                    |
                    v
                   CICS
                    |
                    v
                  COBOL
                    |
                    v
                   Db2

— Abriram um GATE para o mainframe.

O COBOLzeiro arregalou os olhos.

A boa notícia era que os bárbaros do outro lado não carregavam espadas.

A má notícia era que carregavam JSON.

E queriam acessar os dados do reino.

Bem-vindo ao mundo das APIs.



🏰 CAPÍTULO 1 — ANTES DE ENTENDER API, ENTENDA O PROBLEMA

Vamos começar absolutamente do zero.

Imagine dois programas.

O primeiro possui determinada informação.

O segundo precisa dessa informação.

Precisamos criar uma maneira de eles conversarem.

Dentro de um mesmo programa COBOL podemos simplesmente executar:

PERFORM CALCULA-SALDO

Ou talvez:

CALL 'PGMSALDO' USING WS-CONTA
                      WS-SALDO.

O problema começa quando o consumidor está em outro ambiente.

Imagine:

Aplicativo celular
        |
        ?
        |
     Mainframe

O aplicativo não pode executar:

CALL 'PGMSALDO'

através da Internet.

Precisamos de uma interface.

É aí que surge a ideia de uma API — Application Programming Interface.

Podemos simplificar inicialmente:

API é um contrato que permite que um software solicite serviços ou informações de outro software.

A palavra importante é contrato.

Não pense apenas em:

URL

Pense em:

O que posso pedir?
Como devo pedir?
Quem pode pedir?
Que dados preciso enviar?
O que receberei?
Como saberei que funcionou?
Como saberei que falhou?
Posso tentar novamente?
Quantas vezes posso chamar?
O contrato poderá mudar?

Essas perguntas formam a arquitetura de uma API.



🚪 CAPÍTULO 2 — ENDPOINT: ITAMI ENCONTROU O PRIMEIRO PORTAL

Em GATE, existe uma passagem ligando dois mundos.

Uma API possui algo conceitualmente parecido.

Um endpoint é um ponto através do qual determinada funcionalidade ou recurso pode ser acessado.

Imagine:

GET /customers/123

Podemos interpretar como:

Quero consultar o cliente 123.

Outro endpoint:

GET /accounts/987/balance

Significa:

Quero consultar o saldo da conta 987.

Não precisamos revelar ao consumidor que atrás daquele endpoint existe:

z/OS Connect
     |
     v
CICS
     |
     v
PGMSALD0
     |
     v
Db2

Essa abstração é extremamente importante.

O aplicativo conhece:

/accounts/987/balance

Não precisa conhecer:

LPAR
CICS region
transaction ID
program name
COMMAREA
Db2 subsystem
table

Itami provavelmente diria:

O GATE permite chegar ao reino. Você não precisa entregar ao visitante a planta completa do castelo.

Excelente princípio de segurança também.



⚔️ CAPÍTULO 3 — HTTP METHODS: NÃO BASTA CHEGAR AO PORTAL

Agora precisamos dizer o que queremos fazer.

Os métodos HTTP mais conhecidos são:

GET
POST
PUT
PATCH
DELETE

GET

Normalmente utilizado para consultar.

GET /customers/123

POST

Frequentemente usado para criar um recurso ou iniciar uma operação.

POST /payments

PUT

Normalmente utilizado para substituir ou atualizar integralmente determinada representação.

PATCH

Alteração parcial.

PATCH /customers/123

DELETE

Solicita remoção.

DELETE /customers/123

Para o programador COBOL podemos fazer uma analogia imperfeita, mas didática:

GET       → consulta
POST      → inclusão/processamento
PUT/PATCH → alteração
DELETE    → exclusão

Quem trabalhou com CRUD reconhecerá:

CREATE
READ
UPDATE
DELETE

Mas HTTP possui semântica própria. Não devemos simplesmente tratar os métodos como nomes diferentes para a mesma coisa.



📦 CAPÍTULO 4 — REQUEST E RESPONSE: A COMMAREA DO OUTRO MUNDO

Agora Itami atravessa o GATE carregando uma mensagem.

Temos uma request, a requisição.

Por exemplo:

POST /payments
Content-Type: application/json
Authorization: Bearer <token>

Com:

{
  "account": "123456",
  "amount": 150.00
}

Para quem vem do CICS, podemos pensar didaticamente:

“Então JSON é uma COMMAREA?”

Não exatamente.

Mas a analogia ajuda inicialmente.

Em uma transação CICS tradicional poderíamos receber uma estrutura definida.

No universo API, o contrato pode determinar um JSON:

{
  "customerId": 123,
  "amount": 150.00,
  "currency": "BRL"
}

O servidor processa e envia uma response:

{
  "transactionId": "ABC987",
  "status": "APPROVED"
}

O fluxo torna-se:

REQUEST
   |
   v
API
   |
   v
PROCESSAMENTO
   |
   v
RESPONSE

Parece simples.

Até a rede falhar.

Guarde essa informação.

Ela voltará para nos assombrar.


🚦 CAPÍTULO 5 — STATUS CODE: COMO SABER SE ITAMI VOLTOU VIVO?

HTTP possui códigos que indicam o resultado da requisição.

Alguns fundamentais:

200 OK
201 Created
204 No Content

400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
409 Conflict
429 Too Many Requests

500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout

Eles são divididos em famílias.

2xx → sucesso
4xx → problema relacionado à requisição/cliente
5xx → problema no servidor ou infraestrutura

Um erro muito comum é responder sempre:

200 OK

e colocar dentro do JSON:

{
  "success": false
}

Pode funcionar, mas prejudica ferramentas que dependem da semântica HTTP.

Imagine o dashboard:

Requests HTTP 200: 100%

Operações efetivamente realizadas:

47%

Monitoramento:

TUDO VERDE!

Produção:

🔥🔥🔥🔥🔥

Às 03:17, alguém descobrirá a diferença.

Eis nosso primeiro easter egg.


🔐 CAPÍTULO 6 — AUTENTICAÇÃO E AUTORIZAÇÃO: RACF EXPLICA ISSO MUITO BEM

Dois conceitos são frequentemente confundidos.

Authentication

Pergunta:

Quem é você?

Authorization

Pergunta:

O que você pode fazer?

O programador de mainframe possui uma vantagem aqui.

Imagine RACF.

Você pode autenticar-se no sistema:

USER01

Isso não significa que automaticamente pode acessar:

SYS1.PARMLIB

Primeiro:

IDENTIDADE

Depois:

PERMISSÃO

No mundo das APIs:

Cliente
   |
Authentication
   |
Identidade conhecida
   |
Authorization
   |
Pode executar POST /payments?

Essa separação é crucial.

Um usuário pode ter permissão para:

GET /accounts/123

mas não:

DELETE /accounts/123

Autenticação sem autorização seria como reconhecer perfeitamente o invasor e, depois disso, entregar-lhe as chaves.


🎫 CAPÍTULO 7 — ACCESS TOKENS: O PASSE PARA ATRAVESSAR O GATE

Imagine que Itami receba uma credencial temporária para atravessar determinada área.

No universo das APIs podemos utilizar access tokens.

Em vez de transmitir usuário e senha em cada operação, temos conceitualmente:

Autenticação
     |
     v
Access Token
     |
     v
Requisições

Exemplo:

Authorization: Bearer eyJ...

O token pode carregar ou estar associado a informações de autorização.

Mas há uma regra importante:

Token deve ser tratado como segredo.

Não queremos tokens vazando em:

logs
Git
URLs
prints
tickets
mensagens
telemetria

Aqui encontramos um paradoxo interessante.

Para investigar incidentes queremos muitos logs.

Para proteger sistemas não queremos registrar segredos.

Portanto:

Observabilidade também precisa ser projetada com segurança.


🛂 CAPÍTULO 8 — OAUTH 2.0: ITAMI NÃO ENTREGA SUA SENHA PARA TODO MUNDO

OAuth 2.0 costuma ser explicado de maneira excessivamente simplificada como “sistema de login”.

O conceito central está relacionado à autorização delegada.

Imagine uma aplicação que precisa acessar determinado recurso em seu nome.

Você não deveria simplesmente entregar sua senha para ela.

A ideia é estabelecer mecanismos pelos quais determinada aplicação recebe autorização limitada.

Isso fica ainda mais importante quando entramos no mundo dos agentes de IA.

Imagine:

AI Agent
   |
   +----> Calendar API
   |
   +----> Email API
   |
   +----> CRM API
   |
   +----> Mainframe API

Agora aparecem perguntas novas:

Quem é o agente?

Quem autorizou?

Que ferramentas ele pode usar?

Quais operações?

Por quanto tempo?

Pode transferir dinheiro?

Pode excluir dados?

Precisa de aprovação humana?

Perceba como uma API tornou-se também uma fronteira de autoridade.


🚧 CAPÍTULO 9 — RATE LIMITING E THROTTLING: NEM TODO MUNDO ATRAVESSA O GATE AO MESMO TEMPO

Imagine 500 pessoas tentando atravessar simultaneamente uma passagem que comporta dez.

Temos um problema de capacidade.

APIs também enfrentam isso.

Rate limiting

Podemos estabelecer:

100 requests/minuto

Se o cliente ultrapassar:

429 Too Many Requests

Throttling

Podemos controlar deliberadamente o ritmo das requisições para proteger recursos.

Imagine:

Internet
  |
100.000 req/s
  |
  v
API Gateway
  |
  | fluxo controlado
  v
CICS

Isso possui conexão direta com um conceito que mainframe conhece muito bem:

Workload Management

Controlar carga, prioridades e recursos não foi inventado pelos microsserviços.

O mainframe vem resolvendo problemas semelhantes há décadas.


📚 CAPÍTULO 10 — PAGINATION: NÃO TRAGA O REINO INTEIRO EM UMA REQUEST

Considere:

GET /transactions

Agora imagine uma instituição com 800 milhões de transações.

Quer devolver tudo?

Espero que não.

Utilizamos paginação.

Exemplo:

GET /transactions?page=1&size=100

Ou:

GET /transactions?cursor=ABCXYZ

Assim recebemos pequenas partes.

Isso parece detalhe de interface, mas pode afetar profundamente:

Db2
CPU
I/O
memória
rede
tempo de resposta

Uma API mal desenhada pode produzir uma consulta gigantesca no backend.

E aquele endpoint inocente:

GET /transactions

vira o dragão da dungeon.


⚡ CAPÍTULO 11 — CACHE: ITAMI GUARDA SUPRIMENTOS PERTO DO PORTAL

Imagine buscar repetidamente o mesmo material em uma cidade a 300 quilômetros.

Faz sentido manter um estoque próximo.

Cache utiliza raciocínio semelhante.

Request
   |
   v
Cache
   |
   +-- HIT --> Response
   |
   +-- MISS --> Backend

Benefícios:

menor latência
menos processamento
menos I/O
menor carga no backend

Mas surge a pergunta fatal:

Por quanto tempo a informação armazenada continua verdadeira?

Um catálogo talvez possa permanecer alguns minutos em cache.

Saldo bancário exige cuidado muito maior.

Portanto cache não é simplesmente:

CACHE = ON

É uma decisão sobre consistência versus desempenho.

Curiosidade: uma das piadas clássicas da computação diz que existem poucos problemas realmente difíceis, e invalidação de cache invariavelmente aparece na lista.

Não é por acaso.


🔁 CAPÍTULO 12 — IDEMPOTÊNCIA: O MONSTRO QUE COBRA DUAS VEZES

Agora chegamos a um dos conceitos mais importantes de toda a dungeon.

Imagine:

POST /payments

R$ 1.000

O servidor recebe.

Processa.

Debita.

Mas a resposta desaparece na rede.

O cliente vê:

TIMEOUT

O que aconteceu?

Talvez nada.

Talvez tudo.

Esse é o detalhe fundamental:

Timeout não significa necessariamente que a operação falhou.

Significa:

O cliente não conseguiu determinar o resultado.

Então ele tenta novamente:

POST /payments

R$ 1.000

Sem proteção:

primeiro débito  = R$ 1.000
segundo débito   = R$ 1.000

Parabéns.

Criamos uma reclamação bancária.

Uma estratégia é utilizar uma Idempotency-Key:

Idempotency-Key: OPERATION-ABC123

Primeira chamada:

ABC123 → processada

Segunda:

ABC123 → já conhecida

O servidor pode retornar consistentemente o resultado apropriado sem executar novamente o efeito de negócio.

Para sistemas financeiros, pedidos, reservas e pagamentos, isso é ouro.


🔔 CAPÍTULO 13 — WEBHOOK: PARE DE PERGUNTAR SE A GUERRA TERMINOU

Considere polling:

Terminou?

Não.

Terminou?

Não.

Terminou?

Não.

Terminou?

Não.

Terminou?

Sim.

Ineficiente.

Com webhook:

Quando terminar, avise-me.

Temos:

Sistema A
   |
processamento
   |
   v
evento
   |
   v
Webhook
   |
   v
Sistema B

Muito elegante.

Até percebermos que agora precisamos resolver:

autenticação
retry
timeout
duplicidade
ordenação
assinatura
idempotência
falhas

Essa é uma lição fundamental da arquitetura:

Resolver um problema frequentemente revela a próxima camada de problemas.


🧬 CAPÍTULO 14 — VERSIONAMENTO: O GATE NÃO PODE MUDAR DE LUGAR TODA TERÇA-FEIRA

Você publica:

/v1/customers

Um aplicativo utiliza.

Depois dez.

Depois cinquenta.

Depois quinhentos.

Alguém sugere:

Vamos alterar completamente o contrato.

Calma.

Agora existem consumidores dependentes dele.

Programadores COBOL conhecem perfeitamente esse fenômeno.

Pense em um copybook:

COPY CUSTOMER.

Se 300 programas dependem daquele layout, alterar o copybook não é uma decisão local.

API possui problema semelhante:

API Contract
   |
   +--> Consumer A
   +--> Consumer B
   +--> Consumer C
   +--> Consumer D

Quanto maior a utilização, maior o custo de mudanças incompatíveis.

Uma API bem-sucedida pode transformar-se em infraestrutura.


📜 CAPÍTULO 15 — OPENAPI: O MAPA OFICIAL DO REINO

OpenAPI permite descrever uma API de maneira estruturada.

Podemos documentar:

paths
methods
parameters
schemas
responses
security

Isso possibilita alimentar ferramentas para:

documentação
validação
geração de clientes
mock servers
testes
governança

E existe uma conexão fascinante com IA.

Se um agente possui uma descrição formal das ferramentas disponíveis, fica muito mais fácil determinar:

qual operação existe
quais parâmetros recebe
qual resultado retorna

Assim:

OpenAPI
   +
Tool Calling
   +
LLM
   =
Agente capaz de utilizar serviços

Só que quanto mais fácil tornamos a utilização, mais importante se torna controlar permissão.


🧙 CAPÍTULO 16 — REST VS GRAPHQL: ITAMI DESCOBRE QUE NÃO EXISTE UMA ÚNICA MAGIA

REST é extremamente popular.

Podemos organizar recursos:

/customers
/customers/123
/customers/123/accounts

GraphQL segue outra abordagem.

O consumidor pode solicitar especificamente campos e relações desejados.

Algo conceitualmente como:

customer(id: 123) {
    name
    accounts {
        balance
    }
}

Isso pode reduzir certos problemas de excesso ou insuficiência de dados retornados.

Mas introduz outros desafios:

complexidade das queries
autorização
cache
observabilidade
N+1 queries
controle de recursos

E ainda existem:

gRPC
WebSockets
SSE
MQTT
MQ
Kafka
event streaming

A pergunta madura não é:

REST ou GraphQL, qual é melhor?

É:

Qual modelo de comunicação corresponde ao problema que estou tentando resolver?


🏯 CAPÍTULO 17 — API GATEWAY: O GUARDA DO PORTAL

Finalmente encontramos o personagem que literalmente merece o nome da série.

O API Gateway.

Arquitetura:

                  ┌── Serviço A
                  │
Internet → Gateway├── Serviço B
                  │
                  ├── Cloud
                  │
                  └── Mainframe

Ele pode centralizar funcionalidades como:

routing
authentication
policies
rate limiting
TLS
logging
metrics

Isso é poderoso porque evita implementar determinados controles repetidamente em cada serviço.

Mas cuidado.

Existe a tentação de colocar:

routing
segurança
transformações
regras
orquestração
negócio
validação
mais negócio
mais regras
mais lógica

até que:

API GATEWAY

vire:

NOVO MONÓLITO CORPORATIVO

Itami reconheceria imediatamente a armadilha:

Fortificar o portão não significa construir a cidade inteira dentro dele.


🧩 CAPÍTULO 18 — MICROSSERVIÇOS: 500 SERVIÇOS NÃO SIGNIFICAM 500 VEZES MAIS MODERNIDADE

Existe uma armadilha cultural importante.

Imagine:

Empresa A:
400 microservices

Empresa B:
15 serviços
CICS
MQ
Db2

Não podemos concluir que A seja arquiteturalmente superior.

Microsserviços oferecem vantagens quando existe necessidade real de:

deploy independente
ownership
escalabilidade independente
isolamento
bounded contexts
evolução independente

Mas distribuem problemas.

Agora existem:

rede
latência
timeouts
retries
service discovery
segurança
observabilidade
deployment
versionamento
consistência distribuída

Dentro de um monólito:

PERFORM PROCESSA-PEDIDO

Em arquitetura distribuída:

Service A
    |
    | rede
    v
Service B

E a rede possui uma característica desagradável.

Às vezes ela simplesmente responde:

Não.


💥 CAPÍTULO 19 — ERROR HANDLING: “DEU ERRO” NÃO É UMA ESTRATÉGIA

Uma API precisa possuir tratamento consistente de erros.

Ruim:

{
  "error": "Something went wrong"
}

Também ruim:

{
  "error": "SQLCODE -204 PRODDB.CUSTOMER..."
}

No segundo caso entregamos detalhes internos demais.

Uma resposta melhor poderia ser:

{
  "code": "ACCOUNT_NOT_FOUND",
  "message": "Account does not exist",
  "correlationId": "ABC123"
}

O consumidor recebe informação útil.

A equipe de suporte utiliza:

ABC123

para procurar a operação nos logs.

Isso nos leva à observabilidade distribuída:

Client
  |
ABC123
  |
Gateway
  |
ABC123
  |
Service
  |
ABC123
  |
CICS

Um identificador de correlação ajuda a seguir a aventura inteira.

É quase o SYSOUT da jornada distribuída.


🤖 CAPÍTULO 20 — AGENTES DE IA ATRAVESSARAM O GATE

E chegamos a 2026.

Durante muito tempo tínhamos:

Pessoa
  |
Interface
  |
Aplicação
  |
API

Agora podemos ter:

Pessoa
  |
AI Agent
  |
API
  |
API
  |
API
  |
Mainframe

Isso muda radicalmente a discussão.

Uma API deixa de ser somente um mecanismo utilizado por aplicações previamente programadas.

Pode tornar-se uma ferramenta disponível para um agente escolher e executar.

Imagine as seguintes ferramentas:

consultCustomer()
consultBalance()
createOrder()
cancelOrder()
transferMoney()

Existe enorme diferença de risco entre:

consultBalance()

e:

transferMoney()

Logo precisamos pensar:

Agente
   |
Identidade
   |
Autorização
   |
Policy
   |
Ferramenta permitida?
   |
Aprovação humana necessária?
   |
Execução
   |
Auditoria

A pergunta deixa de ser apenas:

A IA consegue executar?

A pergunta arquiteturalmente importante passa a ser:

A IA possui autoridade para executar, sob quais condições e com qual trilha de auditoria?


🧠 CAPÍTULO 21 — API É ARQUITETURA ORGANIZACIONAL DISFARÇADA DE CÓDIGO

Agora chegamos ao ponto mais profundo da nossa investigação.

Considere:

Equipe A
   |
   API
   |
Equipe B

Aquela API determina:

contrato
dependência
responsabilidade
ownership
SLA
segurança
evolução

Portanto uma API não conecta somente computadores.

Ela conecta equipes e responsabilidades.

Multiplique isso:

Team A ──API── Team B
  │              │
 API            API
  │              │
Team C ──API── Team D

A arquitetura tecnológica começa a refletir a arquitetura organizacional.

Por isso APIs mal projetadas geram uma dívida que pode ficar invisível durante meses.

Depois aparecem:

breaking changes
deployments coordenados
dependências circulares
incidentes
timeouts
retries
duplicidades
problemas de ownership

Finalmente:

WAR ROOM
03:17

O easter egg voltou.

Se você chegou até aqui, ganhou +3270 XP.


🖥️ CAPÍTULO 22 — E ONDE ENTRA O MAINFRAME?

Aqui existe uma das maiores confusões do mercado.

Algumas pessoas ainda imaginam:

API = moderno

Mainframe = antigo

Essa equação está errada.

Podemos perfeitamente ter:

                    Mobile
                      |
Web ─────────── API Gateway ───────── AI Agent
                      |
                  API Layer
                      |
        ┌─────────────┼─────────────┐
        |             |             |
      Cloud          MQ       z/OS Connect
                                    |
                         ┌──────────┴──────────┐
                         |                     |
                        CICS                  IMS
                         |                     |
                       COBOL                 COBOL
                         |                     |
                        Db2                  IMS DB

O COBOL continua executando regras de negócio.

CICS continua gerenciando transações.

Db2 continua armazenando dados.

MQ continua realizando mensageria.

O que mudou?

Criamos novas portas de acesso.

É exatamente como GATE.

A existência do portal não destrói nenhum dos dois mundos.

Ela cria um novo problema de integração entre eles.


⚙️ CAPÍTULO 23 — ESCALABILIDADE É UM PROBLEMA DE COORDENAÇÃO

Esta talvez seja a ideia mais importante de toda a conversa:

Scalability is fundamentally a coordination problem.

Quando alguém fala em escalabilidade, é comum imaginar:

mais CPU
mais memória
mais servidores
mais containers

Mas sistemas distribuídos precisam coordenar:

requisições
estado
identidades
permissões
concorrência
dados
filas
timeouts
retries
falhas
versões
equipes

Podemos possuir enorme capacidade computacional.

Ainda assim duas operações podem tentar modificar simultaneamente o mesmo recurso.

Podemos adicionar containers.

Isso não elimina automaticamente problemas de consistência.

Podemos adicionar microsserviços.

Isso pode aumentar a necessidade de coordenação.

Podemos adicionar agentes de IA.

Agora adicionamos consumidores capazes de decidir dinamicamente quais operações executar.

Cada nova capacidade também aumenta a superfície arquitetural.


🗺️ CAPÍTULO 24 — O MAPA COMPLETO DA DUNGEON

Agora podemos reorganizar os vinte conceitos.

                       API
                        |
        ┌───────────────┼───────────────┐
        |               |               |
     CONTRATO        SEGURANÇA       OPERAÇÃO
        |               |               |
    Endpoint       Authentication    Rate Limit
    Methods        Authorization     Throttling
    Request        OAuth             Pagination
    Response       Tokens            Cache
    Status             |               |
        |               |               |
        └───────────────┼───────────────┘
                        |
                 CONFIABILIDADE
                        |
                   Idempotency
                   Error Handling
                        |
            ┌───────────┴───────────┐
            |                       |
        INTEGRAÇÃO               EVOLUÇÃO
            |                       |
       REST/GraphQL              Versioning
       Webhooks                  OpenAPI
            |                       |
            └───────────┬───────────┘
                        |
                 INFRAESTRUTURA
                        |
                   API Gateway
                        |
                    Services
                        |
          Cloud / MQ / CICS / IMS

Agora aquilo que parecia uma coleção de buzzwords começa a fazer sentido.


🧪 CAPÍTULO 25 — PASSO A PASSO: DESENHANDO UMA API PARA UM PROGRAMA COBOL

Imagine que precisamos disponibilizar consulta de saldo.

Hoje temos:

COBOL → CICS → Db2

Queremos permitir:

Mobile → API → Mainframe

Passo 1 — Defina o recurso

/accounts/{accountId}/balance

Passo 2 — Escolha a operação

Como é consulta:

GET /accounts/123456/balance

Passo 3 — Defina autenticação

Quem pode chamar?

usuário?
aplicação?
parceiro?
agente?

Passo 4 — Defina autorização

Mesmo autenticado:

pode consultar qualquer conta?

somente as próprias?

qual scope?

Passo 5 — Defina response

{
  "accountId": "123456",
  "balance": 3250.45,
  "currency": "BRL"
}

Passo 6 — Defina erros

400 → requisição inválida
401 → não autenticado
403 → sem permissão
404 → recurso não encontrado
429 → excesso de chamadas
500 → erro inesperado
503 → indisponibilidade

Passo 7 — Pense em capacidade

Quantas consultas por segundo?

10?
1.000?
50.000?

Qual impacto no CICS e no Db2?

Passo 8 — Pense em observabilidade

Precisamos acompanhar:

latência
throughput
erros
timeouts
status codes
backend time
correlation ID

Passo 9 — Pense em segurança

Nunca exponha desnecessariamente:

nome do programa COBOL
subsystem
table names
SQL
stack traces
tokens

Passo 10 — Pense no futuro

Se amanhã mudarmos o programa COBOL, o consumidor precisa saber?

Idealmente:

não.

Essa é uma das maiores vantagens da abstração.


🧰 CAPÍTULO 26 — DEZ PERGUNTAS PARA LEVAR PARA QUALQUER PROJETO

Quando alguém disser:

“Precisamos criar uma API.”

Não abra imediatamente o editor.

Pergunte:

  1. Quem é o consumidor?
  2. Qual problema de negócio estamos resolvendo?
  3. Qual é o contrato?
  4. Quem autentica o consumidor?
  5. Quem autoriza cada operação?
  6. Qual volume esperado e qual limite?
  7. O que acontece durante timeout?
  8. A operação pode ser repetida com segurança?
  9. Como monitoraremos ponta a ponta?
  10. Como evoluiremos o contrato sem destruir consumidores existentes?

Essas perguntas podem evitar meses de dívida técnica.


🥚 CURIOSIDADES DA DUNGEON

Muitos dos problemas considerados “moderníssimos” possuem parentes muito mais antigos.

Filas? Mainframes utilizam mensageria há décadas.

Controle de workload? Nada novo para quem conhece z/OS.

Autorização granular? RACF não nasceu ontem.

Contratos entre programas? Copybooks já ensinavam dolorosamente o significado de dependência.

Processamento transacional? CICS poderia dar uma longa aula para muitos microsserviços.

Compatibilidade? O ecossistema IBM Z transformou retrocompatibilidade em uma disciplina praticamente cultural.

Isso não significa que REST, OAuth, Kubernetes ou agentes sejam “a mesma coisa”.

Significa algo muito mais interessante:

Tecnologias mudam rapidamente; problemas fundamentais da computação possuem uma tendência irritante de voltar usando roupas novas.


☕ EPÍLOGO — ITAMI FECHA O MAPA

Depois de atravessar toda a dungeon, o programador COBOL olhou novamente para a primeira definição:

API é uma interface pela qual aplicações se comunicam.

Tecnicamente correta.

Mas insuficiente.

Ele apagou e escreveu:

API é um contrato técnico e operacional que estabelece como diferentes sistemas — e, cada vez mais, diferentes organizações e agentes — podem cooperar com segurança, previsibilidade e capacidade de evolução.

Itami aprovou.

Porque a maturidade não está em conseguir criar:

GET /customer

em quinze minutos.

Está em conseguir responder:

Quem pode chamar?

Quantas vezes?

Qual SLA?

Qual timeout?

Qual retry?

É idempotente?

Como autentica?

Como autoriza?

Como escala?

Como monitoramos?

Como versionamos?

Como descontinuamos?

O que acontece quando o backend cai?

O que acontece quando a resposta desaparece?

O que acontece quando um agente de IA vira consumidor?

Esse é o ponto em que deixamos de falar apenas sobre desenvolvimento de APIs.

Começamos a falar sobre System Design.

E talvez seja justamente aí que o programador COBOL possua uma vantagem que não percebe.

Ele vem de um mundo no qual confiabilidade, transações, segurança, compatibilidade, capacidade, auditoria e operação nunca foram detalhes opcionais.

Agora o restante da arquitetura distribuída está descobrindo a mesma coisa.

O GATE está aberto.

De um lado:

COBOL
CICS
IMS
Db2
MQ
RACF
z/OS

Do outro:

REST
GraphQL
OAuth
OpenAPI
Microservices
Cloud
AI Agents

No meio está o arquiteto.

Sua missão não é escolher qual mundo deve vencer.

É garantir que ambos consigam conversar sem que alguém seja acordado às 03:17 da madrugada porque um retry duplicou 42.000 pagamentos.

E se acontecer?

Bom...

Itami provavelmente estaria de folga.

Porque, afinal, ele tinha planejado passar o fim de semana numa convenção de doujinshi.

END OF JOB — MAXCC=0000.

Vagner Renato Bellacosa, IBM Champion e especialista em IBM Mainframe
IBM Z17 SYSTEM ONLINE
Sobre o autor

Vagner Renato Bellacosa

IBM Champion 2026 • Especialista em IBM Mainframe

Vagner Renato Bellacosa trabalha com IBM Mainframe desde 1988 , é IBM Champion e especialista em COBOL, CICS, Db2, z/OS e IBM Z. Compartilha experiências profissionais, conhecimento técnico, história da computação e práticas do universo mainframe para aproximar novas gerações das tecnologias que sustentam empresas, bancos e governos ao redor do mundo.

IBM Champion IBM Z COBOL CICS Db2 z/OS Mainframe desde 1988
GitHub LinkedIn
Inicializando conteúdo...