Sobre
Turmas
Projetos
Time
Materiais
Artigos
Aulas
PT
EN
Materiais
Materiais
· Backend
4. JSON e Contratos de API
Introdução a JSON e contratatos
20 min de leitura
→
Anterior
3. HTTP a Linguagem das APIs
Próximo
5. REST e Design de APIs
→
Nesta página
4.0. Visão Geral: Dados e Contratos
O que você vai aprender neste módulo?
A Base (O Formato)
A Mecânica (Serialização)
As Regras (Contratos)
A Formalização (OpenAPI)
O Tratamento de Problemas
Por que isso é importante?
4.1. JSON como formato de troca de dados
Ficha Técnica do JSON
Estrutura do JSON
Exemplo visual
Por que JSON domina o mercado
1) Simplicidade e Leveza
2) Compatibilidade Nativa
3) Legibilidade
Contexto Histórico e Outros Usos
Regras de Ouro (Sintaxe Estrita)
Exemplo guiado: De objeto para JSON
Checklist rápido
Fontes
4.2. Tipos, estruturas e armadilhas comuns
Os Tipos de Dados do JSON
Armadilhas Comuns (Onde os bugs moram)
1) A falta de Data e Hora
2) Números e Precisão
3) Null vs Ausência de Chave
4) Decimais e Dinheiro
Exemplo guiado: Um JSON robusto
Ruim (Frágil)
Bom (Robusto)
Checklist rápido
Fontes
4.3. Serialização e deserialização
O Conceito
Serialização (Marshalling)
Deserialização (Unmarshalling)
O Custo Oculto
Convenções de Nomes (Case Styles)
Segurança na Deserialização
Exemplo guiado: Serialização com Pydantic (FastAPI)
Checklist rápido
Fontes
4.4. Contratos de entrada e saída
Responsabilidades Distintas
Contrato de Entrada (Input)
Contrato de Saída (Output)
Lei de Postel (Princípio da Robustez)
Exemplo Guiado: Cadastro no Trilha
Contrato de Entrada (Request Body)
Contrato de Saída (Response Body)
DTOs (Data Transfer Objects)
Checklist rápido
Fontes
4.5. Evolução de contratos e compatibilidade
Breaking Changes (Mudanças de Quebra)
Non-Breaking Changes (Mudanças Compatíveis)
Estratégias de Evolução
1) Apenar Adicionar (Additive Changes)
2) Padrão Expand-Contract
3) Versionamento
O Mito do "Vou mudar rapidinho"
Checklist rápido
Fontes
4.6. OpenAPI como contrato formal
O que é OpenAPI?
Por que usar?
1) Documentação Interativa
2) Geração de Código (SDKs)
3) Testes Automatizados
Code-First vs Schema-First
Code-First (Abordagem do FastAPI)
Schema-First (Design-First)
Exemplo de OpenAPI (YAML)
Checklist rápido
Fontes
4.7. Modelagem consistente de erros
O Anti-padrão do "200 OK com erro"
Padronizando o Formato (RFC 7807)
Campos principais:
Erros de Validação (Múltiplos erros)
Segurança nos Erros
Checklist rápido
Fontes