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.