Bellacosa Mainframe apresenta o Swagger

☕ Um Café no Bellacosa Mainframe

📚 EINA TULLE E O GRIMÓRIO QUE ENSINOU O COBOL A FALAR REST

Swagger, OpenAPI, REST, HTTP, JSON, YAML, APIs, contratos, Swagger UI, autenticação, OAuth, JWT, RACF, CICS, IMS, Db2, VSAM, z/OS Connect, CI/CD, observabilidade — e o dia em que um programador COBOL descobriu que 200 OK não significava que a aventura havia terminado.

Sob a tutela de Eina Tulle, de Is It Wrong to Try to Pick Up Girls in a Dungeon?

---

🎬 PRÓLOGO — BEM-VINDO À GUILDA, AVENTUREIRO

Imagine um jovem programador COBOL chegando para seu primeiro dia em uma grande empresa.

Ele conhece algumas coisas:

IDENTIFICATION DIVISION.
PROGRAM-ID. CONSULTA.

DATA DIVISION.
WORKING-STORAGE SECTION.

01 WS-CLIENTE.
   05 WS-ID       PIC 9(09).
   05 WS-NOME     PIC X(40).

JCL ele está começando a entender.

Já ouviu falar de CICS.

Db2 ainda parece uma dungeon particularmente perigosa.

E então alguém aparece e diz:

— Precisamos criar uma API REST usando OpenAPI.

Nosso aventureiro olha para a tela como Bell Cranel provavelmente olharia para uma criatura vários níveis acima do seu.

API? REST? Swagger? OpenAPI? JSON?

É nesse momento que Eina Tulle empurra seus óculos, abre uma enorme pilha de documentos sobre a mesa da Guilda e responde:

— Antes de entrar na Dungeon, você precisa conhecer o mapa.

E talvez essa seja a melhor definição inicial de OpenAPI para um programador COBOL.

OpenAPI é parte do mapa.

Não é o monstro.

Não é a espada.

Não é o aventureiro.

É uma descrição formal de como encontrar e utilizar aquilo que existe do outro lado da porta.

E essa porta pode terminar justamente em um programa COBOL.

---

📜 CAPÍTULO 1 — QUANDO NASCEU O SWAGGER?

Nossa história começa muito depois do nascimento do COBOL.

COBOL surgiu em 1959.

CICS apareceu no final da década de 1960.

Db2 chegou comercialmente na década de 1980.

Swagger é praticamente uma criança perto deles.

A especificação Swagger foi criada na Wordnik em 2010 e publicada como projeto open source no ano seguinte. Em 2015, os direitos do projeto foram adquiridos pela SmartBear; naquele mesmo ano, a especificação foi doada para a recém-formada OpenAPI Initiative, sob a Linux Foundation. O Swagger 2.0 tornou-se a base do que passou a ser chamado de OpenAPI Specification. (OpenAPI Initiative)

Portanto:

1959       COBOL
  │
1969       CICS
  │
1980s      Db2
  │
2010       Swagger nasce
  │
2011       projeto/spec é publicado como open source
  │
2015       OpenAPI Initiative
  │
2017       OpenAPI 3.0
  │
2025       OpenAPI 3.2

Em setembro de 2025 foi publicada a especificação OpenAPI 3.2.0. (OpenAPI Initiative Publications)

Curiosamente, enquanto escrevemos em 2026, a página oficial de versões já lista também a 3.2.1. (OpenAPI Initiative Publications)

Mas aqui existe uma regra importantíssima para quem trabalha com mainframe:

A versão mais recente de um padrão não significa automaticamente a versão suportada por cada produto da sua arquitetura.

O IBM z/OS Connect, por exemplo, documenta seus próprios níveis suportados de OpenAPI. Portanto, consulte a matriz do produto antes de simplesmente colocar a versão mais nova no projeto.

Eina escreveria isso no topo da ficha do aventureiro:

Conheça a Dungeon antes de comprar a espada.

---

🧩 CAPÍTULO 2 — SWAGGER NÃO É OPENAPI

Esta é provavelmente a confusão mais comum.

Durante muito tempo Swagger era tanto o nome da especificação quanto do ecossistema.

Depois da criação da OpenAPI Initiative, houve uma separação conceitual.

Hoje podemos pensar:

OPENAPI
     ↓
ESPECIFICAÇÃO / CONTRATO

SWAGGER
     ↓
FERRAMENTAS / ECOSSISTEMA

A OpenAPI Specification é uma descrição padronizada e independente de linguagem para APIs HTTP. Ela permite que pessoas e programas descubram as capacidades de um serviço sem precisar examinar seu código-fonte. (OpenAPI Initiative Publications)

Já no universo Swagger encontramos ferramentas para trabalhar com esse contrato.

Por exemplo:

Swagger UI
Swagger Editor
Swagger Codegen

Então grave:

OpenAPI descreve. Swagger ajuda você a trabalhar com essa descrição.

Não diga simplesmente:

“Swagger é uma API.”

Não é.

---

📖 CAPÍTULO 3 — OPENAPI É O COPYBOOK DA FRONTEIRA?

Eina provavelmente faria uma analogia para nosso aprendiz COBOL.

Considere:

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

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

Um programador COBOL imediatamente reconhece que existe uma estrutura.

Agora observe uma representação externa:

Cliente:
  type: object
  properties:
    id:
      type: integer
    nome:
      type: string
    status:
      type: string
    limite:
      type: number

A semelhança conceitual ajuda.

Mas cuidado.

OpenAPI não é literalmente um COPYBOOK moderno.

OpenAPI consegue descrever muito mais sobre a interface HTTP:

URL
paths
operações
parâmetros
headers
request
response
schemas
autenticação
status codes

Podemos dizer didaticamente:

COPYBOOK
   ↓
estrutura utilizada pelo programa

OPENAPI
   ↓
contrato da interface HTTP

O COPYBOOK pode dizer como o COBOL enxerga determinado dado.

OpenAPI pode dizer como o mundo exterior conversa com o serviço.

---

🌐 CAPÍTULO 4 — A PORTA DA DUNGEON CHAMA-SE ENDPOINT

Suponha:

GET /api/clientes/101?page=2

Temos diferentes componentes:

GET                 HTTP METHOD

/api/clientes       PATH

101                 PATH PARAMETER

page=2              QUERY PARAMETER

O path parameter normalmente participa da identificação do recurso.

Exemplo:

/clientes/101
/clientes/102
/clientes/103

Já query parameters frequentemente aparecem em filtros, paginação, ordenação etc.:

/clientes?page=2

/clientes?cidade=Itatiba

/clientes?status=ativo&sort=nome

Para quem veio do COBOL, não há magia nisso.

Estamos simplesmente recebendo dados através de outra interface.

---

🏰 CAPÍTULO 5 — MAS COMO ISSO CHEGA AO MAINFRAME?

Agora entramos na parte divertida.

Imagine:

MOBILE
   │
   │ HTTPS / JSON
   ▼
API GATEWAY
   │
   ▼
z/OS CONNECT
   │
   ▼
CICS
   │
   ▼
COBOL
   │
   ├────────► Db2
   │
   └────────► VSAM

O programa COBOL não precisa transformar-se magicamente em JavaScript.

O IBM z/OS Connect pode atuar como uma camada entre APIs REST e recursos z/OS. A documentação da IBM descreve API providers capazes de transformar requisições REST em chamadas aos subsistemas z/OS e converter dados entre JSON e estruturas nativas consumíveis por COBOL, PL/I e C. (IBM)

Isso é extraordinariamente importante.

Externamente alguém manda:

{
  "clienteId": 101
}

Internamente podemos terminar com algo semelhante a:

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

A interface moderna não precisa destruir o legado.

Ela pode encapsulá-lo.

---

🧙 CAPÍTULO 6 — O GRIMÓRIO OPENAPI

Vamos imaginar uma API:

GET /clientes/{id}

Podemos ter uma descrição OpenAPI simplificada:

openapi: 3.0.3

info:
  title: Cliente API
  version: 1.0.0

paths:
  /clientes/{id}:
    get:
      summary: Consulta cliente
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Cliente encontrado
        '404':
          description: Cliente não encontrado

Eina apontaria para isso e perguntaria:

— Onde está o COBOL?

Não está.

E esse é justamente o ponto.

O consumidor não precisa saber se atrás da API temos:

COBOL
Java
Python
CICS
IMS
Db2
VSAM
um microsserviço
ou três kobolds digitando cartões perfurados.

Ele conhece o contrato.

Isso é desacoplamento.

---

🖥️ CAPÍTULO 7 — SWAGGER UI É O QUADRO DE MISSÕES DA GUILDA

Agora pegamos aquele contrato e apresentamos através de uma interface.

Entra o Swagger UI.

O desenvolvedor consegue explorar coisas como:

GET /clientes/{id}

POST /clientes

PUT /clientes/{id}

DELETE /clientes/{id}

Ele pode encontrar o endpoint, observar parâmetros, analisar schemas e, quando habilitado, executar chamadas diretamente.

O fluxo apresentado nas imagens é muito didático:

OPEN SWAGGER UI
       ↓
FIND ENDPOINT
       ↓
TRY IT OUT
       ↓
ENTER PARAMETERS
       ↓
EXECUTE
       ↓
INSPECT RESPONSE
       ↓
VALIDATE

Excelente para exploração.

Mas existe uma armadilha.

Swagger UI não substitui uma estratégia completa de QA.

---

💚 CAPÍTULO 8 — O TERRÍVEL MONSTRO VERDE: 200 OK

Nosso aventureiro executa:

GET /clientes/101

Swagger fica feliz:

200 OK

Ele comemora.

Eina bate o livro na mesa.

— Ainda não.

Porque 200 OK diz algo sobre o resultado da requisição HTTP.

Não prova automaticamente que a regra de negócio está correta.

Imagine:

{
  "cliente": 101,
  "saldo": 1000000.00
}

O saldo real era:

1000.00

Tecnicamente:

HTTP       OK
JSON       OK
SCHEMA     OK
NEGÓCIO    ERRADO

Isso deveria soar familiar para qualquer mainframer.

É o equivalente a:

MAXCC=0000

e descobrir depois que o arquivo de saída continha valores incorretos.

RC=0 não é sinônimo de negócio correto.

HTTP 200 também não.

---

🧪 CAPÍTULO 9 — O QA PRECISA DESCER MAIS ANDARES

Teste pelo menos:

status HTTP
response body
headers
campos obrigatórios
tipos
schema
valores-limite
dados inválidos
autenticação
autorização
timeout
concorrência
idempotência
rollback
indisponibilidade do backend
performance

Suponha:

POST /pagamentos

Cliente envia:

{
   "conta": "12345",
   "valor": 100
}

O backend processa.

Mas ocorre timeout antes de o cliente receber a resposta.

Ele tenta novamente.

Se não houver desenho adequado:

REQUEST 1 → DEBITA R$100

TIMEOUT

REQUEST 2 → DEBITA R$100

Swagger pode estar perfeitamente configurado.

OpenAPI pode estar impecável.

E você acabou de cobrar o cliente duas vezes.

Bem-vindo ao andar onde moram os monstros de verdade.

---

⚛️ CAPÍTULO 10 — REST NÃO MATOU ACID

Por trás de:

POST /transferencias

pode existir:

UPDATE CONTA A
      ↓
UPDATE CONTA B
      ↓
COMMIT

Se algo falhar:

ROLLBACK

Portanto:

REST
 ↓
JSON
 ↓
z/OS Connect
 ↓
CICS
 ↓
COBOL
 ↓
Db2
 ↓
LOCKS
 ↓
LOG
 ↓
COMMIT / ROLLBACK

A modernização da interface não aboliu cinquenta anos de engenharia transacional.

Isso é uma das coisas mais importantes para um iniciante entender.

API é a porta da Dungeon.

Não é a Dungeon inteira.

---

🔐 CAPÍTULO 11 — “QUEM É VOCÊ?” E “O QUE VOCÊ PODE FAZER?”

Outra imagem traz uma distinção excelente:

AUTHENTICATION
Quem é você?

AUTHORIZATION
O que você pode fazer?

Podemos encontrar mecanismos como:

Basic Authentication
API Key
Bearer Token
JWT
OAuth 2.0

Agora transporte isso para IBM Z:

APP
 │
 ▼
OAuth / OIDC
 │
 ▼
TOKEN
 │
 ▼
API GATEWAY
 │
 ▼
z/OS Connect
 │
 ▼
SAF / RACF
 │
 ▼
CICS
 │
 ▼
COBOL

Surge uma pergunta arquitetural fundamental:

Qual identidade chega ao recurso protegido?

Porque autenticar alguém na primeira porta não significa automaticamente permitir qualquer operação atrás dela.

É justamente daí que nasce a distinção didática entre:

401
problema de autenticação/credenciais

403
identidade reconhecida,
mas acesso não permitido

A própria oferta atual do z/OS Connect destaca autorização granular por operação para serviços de negócio. (IBM)

---

🚨 CAPÍTULO 12 — NÃO MANDE SQLCODE -911 PARA O CLIENTE

Imagine:

EXEC SQL
   SELECT SALDO
     INTO :WS-SALDO
     FROM CONTA
    WHERE ID = :WS-ID
END-EXEC

Alguma condição ocorre no Db2.

Você não deveria transformar automaticamente sua implementação interna em contrato público:

{
   "sqlcode": -911
}

Muito menos:

{
   "abend": "ASRA",
   "program": "XPTO1234"
}

Você está vazando detalhes da implementação.

O ideal é existir um mapeamento coerente entre erro interno e contrato externo.

Por exemplo:

Db2: registro inexistente
        ↓
regra da aplicação
        ↓
HTTP 404

Resposta:

{
   "code": "ACCOUNT_NOT_FOUND",
   "message": "Conta não encontrada"
}

Internamente você preserva informações suficientes para diagnóstico:

timestamp
transaction ID
correlation ID
program
CICS transaction
SQLCODE
trace
logs
SMF

O usuário recebe aquilo que precisa.

Operações recebe aquilo que precisa.

Segurança agradece.

---

🏗️ CAPÍTULO 13 — API-FIRST: DESENHE A MISSÃO ANTES DE ENTRAR NA DUNGEON

Aqui encontramos uma transformação particularmente interessante para equipes mainframe.

Tradicionalmente poderíamos imaginar:

COBOL
 ↓
interface
 ↓
documentação

API-first inverte parte desse raciocínio.

Primeiro definimos:

CONTRATO
 ↓
IMPLEMENTAÇÃO

Imagine:

POST /transferencias

Request:

{
   "origem": "123456",
   "destino": "987654",
   "valor": 250.00
}

Response:

{
   "transacao": "TRX829173",
   "status": "EFETIVADA"
}

Agora várias equipes podem trabalhar sobre o mesmo contrato:

           OpenAPI
              │
    ┌─────────┼──────────┐
    │         │          │
 Mobile      QA       Mainframe
    │         │          │
    ▼         ▼          ▼
 cliente    testes    implementação

E isso não é apenas teoria aplicada ao IBM Z. A IBM documenta desenvolvimento API-first no z/OS Connect usando documentos OpenAPI e ferramentas que geram artefatos de projeto e estruturas de linguagem necessárias à implementação, inclusive para aplicações CICS COBOL ou PL/I. (IBM)

A funcionalidade API-first foi introduzida no z/OS Connect 3.0.69. (IBM)

Para o COBOLzeiro, isso é enorme.

O contrato deixa de ser aquele PDF que alguém atualiza seis meses depois.

Ele passa a participar do processo de engenharia.

---

🔄 CAPÍTULO 14 — DO SWAGGER AO CI/CD

Agora podemos expandir o workflow apresentado nas imagens:

BUSINESS REQUIREMENT
          ↓
     API DESIGN
          ↓
   OPENAPI CONTRACT
          ↓
    CONTRACT REVIEW
          ↓
        MOCK
          ↓
   BACKEND DEVELOPMENT
          ↓
     z/OS CONNECT
          ↓
     CICS / IMS
          ↓
        COBOL
          ↓
    Db2 / VSAM
          ↓
 FUNCTIONAL TEST
          ↓
 NEGATIVE TEST
          ↓
 CONTRACT TEST
          ↓
 SECURITY TEST
          ↓
 PERFORMANCE TEST
          ↓
       CI/CD
          ↓
      DEPLOY
          ↓
    PRODUCTION

E isso destrói outro mito:

“DevOps não serve para mainframe.”

Serve.

O que muda são ferramentas, processos, controles e características da plataforma.

---

🔭 CAPÍTULO 15 — A AVENTURA NÃO TERMINA NO DEPLOY

Produção não é:

DEPLOY
  ↓
FIM

Produção é:

DEPLOY
  ↓
OBSERVAR
  ↓
MEDIR
  ↓
INVESTIGAR
  ↓
CORRIGIR

Por isso nosso desenho final começa a ganhar novas peças:

API
 ↓
z/OS Connect
 ↓
CICS
 ↓
COBOL
 ↓
Db2

        ↘ TELEMETRIA
             ↓
        OBSERVABILIDADE

O z/OS Connect também oferece integração com mecanismos tradicionais do z/OS, incluindo rastreamento via SMF, e a linha atual oferece suporte a OpenTelemetry para observabilidade. (IBM)

Isso cria uma combinação particularmente poderosa:

OpenAPI
   =
O QUE FOI CONTRATADO

telemetria
   =
O QUE ESTÁ ACONTECENDO

Quando ambos se encontram, você deixa de simplesmente publicar APIs e começa a operá-las profissionalmente.

---

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

Depois da aula de Eina, nosso jovem COBOLzeiro finalmente consegue desenhar:

                    CONSUMIDORES
                         │
               Web / Mobile / Cloud
                         │
                         ▼
                    HTTPS / REST
                         │
                         ▼
                 ┌───────────────┐
                 │ API CONTRACT  │
                 │    OpenAPI    │
                 └───────┬───────┘
                         │
                 Swagger UI
                         │
                         ▼
                    API GATEWAY
                         │
                   OAuth / JWT
                         │
                         ▼
                  z/OS CONNECT
                         │
           ┌─────────────┼─────────────┐
           │             │             │
           ▼             ▼             ▼
         CICS           IMS           Db2
           │             │
           ▼             ▼
         COBOL         COBOL
           │             │
           └──────┬──────┘
                  │
          ┌───────┼────────┐
          ▼       ▼        ▼
         Db2     VSAM     IMS DB
          │
          ▼
    COMMIT / ROLLBACK
          │
          ▼
    SMF / TELEMETRIA
          │
          ▼
    OBSERVABILIDADE

Agora Swagger deixou de parecer uma tecnologia alienígena.

É apenas mais uma peça da arquitetura.

---

💡 CAPÍTULO 17 — DEZ CONSELHOS DE EINA PARA O COBOLZEIRO

Antes de liberar nosso aventureiro para a Dungeon, Eina deixaria algumas regras no quadro da Guilda:

1. Não confunda Swagger com OpenAPI. Um é o ecossistema de ferramentas; o outro é a especificação.

2. Não trate Swagger UI como ferramenta completa de QA. Explorar endpoints é apenas o começo.

3. Nunca comemore apenas porque recebeu 200 OK. Valide o negócio.

4. Não exponha detalhes internos desnecessários. SQLCODE, ABEND e nomes internos não precisam virar sua interface pública.

5. Teste erros deliberadamente. Token inválido, campo ausente, valor absurdo, backend indisponível e timeout também fazem parte da API.

6. Pense em idempotência. Principalmente pagamentos e operações financeiras.

7. Separe autenticação de autorização.

8. Versione e governe o contrato. Alterar uma API usada por dezenas de consumidores é muito diferente de alterar uma rotina interna isolada.

9. Use observabilidade desde o desenho. Não espere o primeiro incidente para perguntar como correlacionar uma requisição HTTP com o processamento z/OS.

10. Não tente transformar COBOL em REST. Crie uma arquitetura em que REST e COBOL façam aquilo que cada tecnologia sabe fazer bem.

---

🥚 EASTER EGG — A REQUISIÇÃO DAS 03:17

Algumas semanas depois, produção recebe:

03:17:00.317

Uma chamada:

POST /transferencias

Swagger dizia:

201 Created

O dashboard estava verde.

CPU normal.

z/OS saudável.

CICS ativo.

Db2 ativo.

Nenhum grande alarme.

Mesmo assim, o cliente reclamava:

“Minha transferência apareceu duas vezes.”

Nosso jovem programador quase responde:

— Mas recebemos 201!

Ele para.

Lembra da aula.

Procura o correlation ID.

Segue a requisição.

API Gateway.

z/OS Connect.

CICS.

COBOL.

Db2.

COMMIT.

Depois encontra uma segunda requisição, enviada após um timeout do consumidor.

Mesmo payload.

Mesmo valor.

Outro processamento.

E então finalmente compreende a verdadeira lição daquela primeira aventura:

Disponibilidade não garante correção. HTTP correto não garante negócio correto. E observabilidade sem contexto é apenas uma coleção muito cara de luzes verdes.

No dia seguinte ele volta à Guilda.

Eina pergunta:

— Então, aprendeu Swagger?

Ele responde:

— Não.

Ela ergue uma sobrancelha.

— Aprendi sistemas.

Agora ela sorri.

---

☕ EPÍLOGO — O MAINFRAME NÃO PRECISA APRENDER A SER JOVEM

Existe uma narrativa recorrente na tecnologia:

velho
versus
novo

Mainframe versus cloud.

COBOL versus Java.

CICS versus microsserviços.

Batch versus APIs.

Essa oposição frequentemente é simplista.

Uma arquitetura moderna pode perfeitamente conter:

OpenAPI
Swagger
REST
JSON
OAuth
API Gateway
z/OS Connect
RACF
CICS
COBOL
Db2
VSAM
SMF
OpenTelemetry
CI/CD

Não existe contradição nisso.

Existe integração.

A aplicação mobile não precisa conhecer PIC, COMP-3, COMMAREA ou SQLCODE.

O programa COBOL não precisa conhecer detalhes da interface gráfica do smartphone.

Entre os dois existe um contrato.

OpenAPI.

E ferramentas como Swagger ajudam pessoas e máquinas a compreender e trabalhar com esse contrato.

O IBM z/OS Connect completa uma parte importantíssima dessa ponte, expondo recursos z/OS através de APIs e realizando transformações entre o universo REST/JSON e estruturas utilizadas pelas aplicações z/OS. (IBM)

Talvez seja essa a maior lição sob a tutela de Eina Tulle.

Ela jamais mandaria um aventureiro para a Dungeon simplesmente porque ele tinha uma espada nova.

Primeiro ensinaria:

o mapa
os níveis
os monstros
as regras
as rotas
os riscos
e como voltar vivo.

Swagger UI é uma ferramenta.

OpenAPI é um contrato.

REST é um estilo arquitetural.

HTTP é um protocolo.

JSON é uma representação de dados.

OAuth pode participar da segurança.

z/OS Connect pode fazer a ponte.

CICS pode administrar a transação.

COBOL pode executar a regra de negócio.

Db2 pode preservar os dados.

RACF/SAF pode participar da proteção.

SMF e OpenTelemetry podem ajudar a contar o que aconteceu.

Nenhuma dessas peças, sozinha, é “a modernização”.

A arquitetura aparece quando sabemos como todas elas se relacionam.

E é justamente por isso que talvez a pergunta mais interessante não seja:

“Como substituir COBOL por APIs?”

Mas:

“Como fazer décadas de lógica de negócio confiável participarem de um mundo orientado a APIs sem destruir aquilo que já funciona?”

Quando nosso jovem aventureiro consegue responder isso, ele já não está apenas aprendendo Swagger.

Ele começou a compreender o verdadeiro mapa da Dungeon chamada Enterprise Computing.

E em algum lugar, às 03:17, Eina Tulle fecha o último manual da Guilda e escreve na ficha do aventureiro:

LEVEL UP: COBOL PROGRAMMER → API-AWARE MAINFRAMER.

Bellacosa Mainframe e framework FastAPI

☕💣 FastAPI: O Framework Python que Está Conectando a Nova Geração ao Mundo Mainframe

Introdução

Nos últimos anos, poucas tecnologias cresceram tão rapidamente no universo Python quanto o FastAPI. Em um mercado cada vez mais orientado por APIs, microsserviços, computação em nuvem e inteligência artificial, o FastAPI tornou-se uma das ferramentas preferidas para a construção de aplicações modernas.

Mas afinal:

• O que é FastAPI?

• Quem criou?

• Quando surgiu?

• Como funciona?

• Por que ele ficou tão popular?

• Qual sua relação com o universo Mainframe?

Para profissionais acostumados com COBOL, CICS, IMS, DB2 e z/OS, compreender o FastAPI é também entender como as novas aplicações estão consumindo e expondo serviços em arquiteturas distribuídas.

---

A Origem do FastAPI

O FastAPI foi criado por Sebastián Ramírez, desenvolvedor de software da América Latina conhecido na comunidade Python como "tiangolo".

O projeto nasceu da necessidade de criar um framework que reunisse simultaneamente:

• Alto desempenho

• Facilidade de desenvolvimento

• Tipagem forte

• Documentação automática

• Compatibilidade com padrões modernos da web

O lançamento inicial ocorreu em 2018.

Na época, o mercado Python era dominado principalmente por:

• Django

• Flask

• Pyramid

• Tornado

Embora extremamente populares, essas soluções possuíam algumas limitações para aplicações REST modernas.

Sebastián percebeu que era possível criar uma alternativa mais simples e ao mesmo tempo extremamente rápida.

O resultado foi o FastAPI.

---

Licença Open Source

O FastAPI é distribuído sob a licença:

MIT License

Uma das licenças mais permissivas do mercado.

Isso significa que empresas podem:

• Utilizar gratuitamente

• Modificar

• Distribuir

• Incorporar em produtos comerciais

sem necessidade de pagamento de royalties.

Essa característica acelerou sua adoção em bancos, fintechs, seguradoras e grandes corporações.

---

O Que é FastAPI?

FastAPI é um framework para desenvolvimento de APIs REST utilizando Python.

Seu objetivo principal é permitir que desenvolvedores construam serviços web modernos de forma rápida, segura e altamente performática.

De forma simplificada:

Aplicação Cliente
       ↓
API FastAPI
       ↓
Banco de Dados
       ↓
Sistemas Legados
       ↓
Serviços Externos

O FastAPI funciona como uma camada de integração capaz de receber solicitações, processar regras de negócio e retornar respostas.

---

Por Que o Nome "FastAPI"?

A palavra "Fast" não foi escolhida por acaso.

O FastAPI foi projetado para oferecer desempenho extremamente elevado.

Os testes realizados pela comunidade mostram resultados próximos a frameworks escritos em linguagens tradicionalmente mais rápidas, como:

• Go

• Java

• Node.js

• C#

Isso ocorre graças à utilização de componentes modernos do ecossistema Python.

---

Os Pilares do FastAPI

O framework foi construído sobre três tecnologias fundamentais:

Starlette

Responsável pela camada web.

Fornece:

• Rotas

• Requisições HTTP

• Respostas

• WebSockets

É equivalente ao motor que controla o tráfego das requisições.

---

Pydantic

Responsável pela validação dos dados.

Permite garantir que as informações recebidas estejam corretas antes de serem processadas.

Exemplo:

class Cliente(BaseModel):
    codigo: int
    nome: str

Se alguém enviar um valor inválido, o próprio framework rejeita a requisição.

---

Uvicorn

Servidor ASGI utilizado para executar aplicações FastAPI.

Pode ser comparado ao ambiente de execução da aplicação.

---

Como Funciona uma API?

Antes de entender o FastAPI, precisamos entender o conceito de API.

API significa:

Application Programming Interface

Em termos simples:

É uma forma padronizada para que sistemas conversem entre si.

Por exemplo:

Aplicativo Mobile
       ↓
API
       ↓
Sistema Bancário

Quando o usuário consulta o saldo, o aplicativo não acessa diretamente o banco de dados.

Ele chama uma API.

A API consulta os dados e devolve a resposta.

---

O Conceito de Endpoint

No FastAPI, cada serviço é chamado de endpoint.

Exemplo:

@app.get("/clientes")

Significa:

GET /clientes

Quando alguém acessar essa URL, o código correspondente será executado.

Para um profissional de CICS, podemos fazer a seguinte analogia:

Transação CICS
      =
Endpoint REST

Cada endpoint representa uma funcionalidade específica.

---

Exemplo de Código

Um serviço extremamente simples:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def inicio():
    return {
        "mensagem": "Olá Mundo"
    }

Ao acessar:

http://localhost:8000

A resposta será:

{
  "mensagem": "Olá Mundo"
}

---

Tipagem Moderna

Uma das maiores inovações do FastAPI é o uso intensivo de tipagem.

Exemplo:

@app.get("/cliente/{codigo}")
def cliente(codigo:int):
    return {"codigo":codigo}

Observe:

codigo:int

O framework entende automaticamente que o parâmetro deve ser um número inteiro.

Se um valor inválido for informado, a requisição é rejeitada.

---

Documentação Automática

Uma das funcionalidades mais admiradas pelos desenvolvedores.

Ao iniciar a aplicação:

uvicorn main:app --reload

O FastAPI gera automaticamente:

/docs

Utilizando Swagger UI.

E também:

/redoc

Utilizando ReDoc.

Isso elimina horas de documentação manual.

---

JSON: A Linguagem Universal

O principal formato utilizado pelo FastAPI é o JSON.

Exemplo:

{
  "codigo":1001,
  "nome":"Bellacosa"
}

Para quem trabalha com Mainframe, JSON pode ser visto como uma evolução moderna da COMMAREA.

No passado:

01 DFHCOMMAREA.
   05 CODIGO PIC 9(5).
   05 NOME   PIC X(30).

Hoje:

{
   "codigo":1001,
   "nome":"Bellacosa"
}

O objetivo continua sendo o mesmo:

Trocar informações entre sistemas.

---

Operações HTTP

O FastAPI suporta os principais métodos HTTP.

GET

Consulta dados.

@app.get("/clientes")

---

POST

Inclui dados.

@app.post("/clientes")

---

PUT

Atualiza informações.

@app.put("/clientes")

---

DELETE

Remove registros.

@app.delete("/clientes")

---

Segurança

O FastAPI possui recursos avançados de autenticação.

Entre eles:

• OAuth2

• JWT

• API Keys

• LDAP

• Active Directory

• OpenID Connect

Isso permite integração com ambientes corporativos de grande porte.

---

Serviços Modernos Criados com FastAPI

Hoje encontramos FastAPI em:

Bancos

• Consulta de saldo

• PIX

• Open Finance

• Cartões

Seguradoras

• Cálculo de apólices

• Sinistros

E-commerce

• Catálogo

• Pedidos

• Estoque

Saúde

• Prontuários

• Agendamentos

Governo

• Portais digitais

• Serviços públicos

---

FastAPI e Inteligência Artificial

Uma das razões do crescimento explosivo do FastAPI é a Inteligência Artificial.

Ferramentas modernas utilizam FastAPI para expor modelos de IA.

Exemplos:

• Chatbots

• Assistentes virtuais

• Sistemas RAG

• LLMs

• Processamento de documentos

Muitas soluções de IA usam FastAPI como camada de acesso.

---

FastAPI e Mainframe

Aqui encontramos um tema extremamente interessante.

Muitas empresas possuem décadas de investimento em Mainframe.

Os sistemas COBOL continuam executando funções críticas como:

• Contas correntes

• Folha de pagamento

• Processamento de cartões

• Previdência

• Seguros

Entretanto, novas aplicações precisam acessar esses sistemas.

É nesse momento que o FastAPI entra em cena.

---

Cenário Típico de Integração

Imagine:

Aplicativo Mobile
        ↓
FastAPI
        ↓
z/OS Connect
        ↓
CICS
        ↓
Programa COBOL

O usuário realiza uma operação.

A API recebe a solicitação.

O FastAPI chama um serviço no Mainframe.

O COBOL processa a transação.

A resposta retorna em JSON.

---

FastAPI Consumindo Web Services do Mainframe

É comum encontrar arquiteturas como:

FastAPI
     ↓
REST
     ↓
z/OS Connect
     ↓
COBOL

ou

FastAPI
     ↓
SOAP
     ↓
CICS Web Services

Nesse modelo, o FastAPI funciona como uma ponte entre o mundo moderno e os sistemas legados.

---

FastAPI como Camada de Modernização

Muitas organizações utilizam FastAPI para:

• Encapsular sistemas legados

• Expor APIs modernas

• Criar microsserviços

• Construir portais web

• Desenvolver aplicativos móveis

Sem alterar os programas COBOL existentes.

Essa estratégia reduz riscos e custos.

---

Comparação com Tecnologias Mainframe

Mainframe	FastAPI
CICS	Servidor de APIs
Transação	Endpoint
COMMAREA	JSON
COBOL	Python
RACF	OAuth/JWT
BMS	Front-End Web
MQ	APIs REST
Programa Online	Serviço HTTP

---

Vantagens do FastAPI

Entre os principais benefícios estão:

• Desenvolvimento rápido

• Curva de aprendizado simples

• Alto desempenho

• Documentação automática

• Tipagem forte

• Integração com IA

• Integração com Mainframe

• Grande comunidade

• Código limpo

---

Limitações

Nenhuma tecnologia é perfeita.

Algumas limitações incluem:

• Ecossistema mais novo que Django

• Menor quantidade de plugins

• Dependência do Python

• Necessidade de conhecimento de APIs REST

Mesmo assim, seu crescimento continua acelerado.

---

Conclusão

O FastAPI tornou-se uma das tecnologias mais importantes do ecossistema Python moderno. Lançado em 2018 por Sebastián Ramírez sob licença MIT, ele revolucionou a criação de APIs ao combinar simplicidade, velocidade e recursos avançados de validação e documentação.

Para profissionais de Mainframe, o FastAPI não deve ser visto como concorrente do COBOL ou do CICS. Pelo contrário. Ele atua como uma poderosa camada de integração que permite conectar aplicações modernas aos sistemas corporativos que continuam movimentando bilhões de transações diariamente.

Em muitos projetos atuais, o COBOL permanece responsável pelas regras de negócio mais críticas, enquanto o FastAPI assume o papel de porta de entrada para aplicativos móveis, soluções em nuvem, plataformas digitais e sistemas de inteligência artificial.

Em outras palavras, o FastAPI está para a Internet moderna assim como o CICS esteve para o processamento online corporativo durante décadas: uma plataforma capaz de transformar regras de negócio em serviços acessíveis, escaláveis e disponíveis para milhões de usuários.

☕💣 Bellacosa Mainframe Insight: "O COBOL continua guardando as regras de negócio. O FastAPI apenas abre a porta para que o mundo moderno converse com elas."