Manual completo de APIs, integrações e desenvolvimento seguro

Autor do estudo: ChatGPT — preparado para Cleiton Costa
Versão: 1.0
Data de referência: 1º de agosto de 2026
Idioma: Português do Brasil
Escopo: APIs, HTTP, autenticação, integrações, arquitetura, ferramentas, bibliotecas, testes, segurança, operação e APIs de inteligência artificial.

Aviso de atualização: bibliotecas, serviços comerciais, preços, limites, versões e recomendações de segurança mudam. Antes de implementar, confirme a versão atual na documentação oficial. Neste material, versões são citadas quando verificadas em fontes oficiais até a data de referência.

Sumário

Como usar este manual
Modelo mental: o que realmente é uma API
Frontend, backend, banco, API e infraestrutura
O caminho completo de uma chamada
HTTP e HTTPS
Anatomia de uma requisição
Anatomia de uma resposta
Métodos HTTP
Códigos de status
JSON e outros formatos
Quantidade de chamadas, registros, bytes e tokens
Paginação, filtros, ordenação e busca
Estilos de API
REST sem mitologia
Contrato e documentação
Design-first, code-first e API-first
Boas práticas de desenho de endpoints
Erros padronizados
Versionamento e compatibilidade
Idempotência, concorrência e consistência
Cache, compressão e desempenho
Autenticação e autorização
Sessões e cookies
Tokens: conceitos e ciclo de vida
JWT explicado campo por campo
OAuth 2.0, OAuth 2.1 e OpenID Connect
SSO, SAML, LDAP, Active Directory e Kerberos
Hash de senha
Quem configura cada componente
OWASP API Security Top 10
Segurança por camada
Riscos do desenvolvimento assistido por IA
Ferramentas para trabalhar com APIs
Bibliotecas e frameworks por linguagem
Testes de API
Observabilidade e operação
API Gateway e gestão de APIs
Webhooks, filas, eventos e integrações
ERP, Supabase e bancos de dados
APIs de inteligência artificial
Exemplo completo: aplicativo de manutenção
Como solicitar uma API
Perguntas que os desenvolvedores farão
Status de implementação
Critérios de aceite
Roteiro de estudos
Personalidades e autores de referência
Fóruns e comunidades
Documentos e sites oficiais
Glossário

1. Como usar este manual

Este material foi escrito em camadas.

Primeira leitura: seções 2 a 12.
Para conversar com desenvolvedores: seções 15 a 20, 29, 42 a 45.
Para compreender login e tokens: seções 22 a 28.
Para segurança: seções 30 a 32.
Para escolher tecnologias: seções 33 a 40.
Para praticar: seção 41.
Para continuar estudando: seções 46 a 49.

A regra mais importante é não decorar siglas isoladas. Sempre pergunte:

Qual problema isso resolve?
Em qual camada isso atua?
Quem configura?
Qual dado entra?
Qual dado sai?
Como falha?
Como testar?
Como monitorar?
Como revogar ou reverter?
Qual documento oficial define o comportamento?

2. Modelo mental: o que realmente é uma API

API significa Application Programming Interface — Interface de Programação de Aplicações.

Uma API é um contrato técnico de comunicação. Ela define como um software pode solicitar dados ou ações a outro software.

Uma API pode existir em vários contextos:

API web acessada por HTTP;
API de uma biblioteca de programação;
API de um sistema operacional;
API de um equipamento;
API de um ERP;
API de um banco de dados;
API de inteligência artificial;
API industrial de um gateway ou supervisório.

Neste manual, o foco principal são APIs web.

2.1 Analogia correta

Uma API pode ser comparada a um painel de comando autorizado.

O painel:

expõe somente comandos permitidos;
exige parâmetros;
valida permissões;
devolve estados;
não revela necessariamente a implementação interna.

Aplicativo consumidor
        │
        │ requisição
        ▼
Contrato da API
        │
        │ validação e regra de negócio
        ▼
Sistema proprietário dos dados

2.2 A API não é o banco

A API pode consultar um banco, mas não é o banco.

2.3 A API não é necessariamente o backend inteiro

O backend pode possuir:

regras de negócio;
tarefas agendadas;
integrações;
processamento de arquivos;
filas;
banco;
API;
serviços internos.

A API é uma das interfaces do backend.

2.4 A API não é JSON

JSON é apenas um formato de dados frequentemente usado nas mensagens.

2.5 A API não é REST

REST é um estilo arquitetural. Existem APIs REST, RPC, GraphQL, gRPC, SOAP, assíncronas e outras.

3. Frontend, backend, banco, API e infraestrutura

3.1 Frontend

É a interface que o usuário vê e utiliza.

Exemplos:

página web;
aplicativo mobile;
dashboard;
formulário;
tela de login;
painel industrial web.

Responsabilidades típicas:

apresentar dados;
coletar entradas;
validar aspectos básicos de experiência;
chamar o backend;
tratar carregamento e erros;
não expor segredos.

O frontend não deve ser a única camada de segurança. Um usuário pode alterar o JavaScript, interceptar chamadas ou chamar a API diretamente.

3.2 Backend

É onde normalmente ficam:

regras de negócio;
autenticação;
autorização;
validação definitiva;
acesso ao banco;
integrações;
auditoria;
geração de respostas.

3.3 Banco de dados

Armazena dados estruturados ou não estruturados.

Exemplos:

PostgreSQL;
SQL Server;
MySQL;
Oracle;
MongoDB;
Redis.

3.4 Infraestrutura

Inclui:

servidores;
containers;
nuvem;
DNS;
certificados TLS;
firewall;
proxy reverso;
balanceador;
gateway;
rede;
observabilidade;
backups.

3.5 Provedor de identidade

É o sistema que autentica usuários ou aplicações.

Exemplos:

Microsoft Entra ID;
Active Directory Federation Services;
Auth0;
Keycloak;
Okta;
Google Identity;
Supabase Auth;
Amazon Cognito.

3.6 Fluxo resumido

Usuário
  ↓
Frontend
  ↓ HTTPS
Proxy / Gateway
  ↓
API / Backend
  ├── Provedor de identidade
  ├── Banco de dados
  ├── ERP
  ├── Armazenamento
  └── Fila de mensagens

4. O caminho completo de uma chamada

Considere:

https://api.empresa.com/v1/ordens-servico/101

Uma chamada pode envolver:

O aplicativo interpreta a URL.
O DNS converte api.empresa.com em um endereço IP.
Cliente e servidor estabelecem conexão.
TLS protege a comunicação HTTPS.
A requisição HTTP é enviada.
Um firewall ou WAF pode inspecionar o tráfego.
Um balanceador escolhe uma instância.
Um proxy ou API Gateway aplica políticas.
O backend valida a mensagem.
O backend autentica a credencial.
O backend verifica autorização.
A regra de negócio é executada.
O banco ou ERP é consultado.
Logs e métricas são registrados.
A resposta HTTP volta ao cliente.
O frontend apresenta o resultado.

4.1 Componentes que podem existir no caminho

Cliente
  ↓
DNS
  ↓
CDN
  ↓
WAF
  ↓
Load Balancer
  ↓
Reverse Proxy
  ↓
API Gateway
  ↓
Serviço
  ↓
Banco / ERP / fila

Nem todo projeto precisa de todos esses componentes. Adicionar componentes sem necessidade aumenta custo e complexidade.

5. HTTP e HTTPS

HTTP significa Hypertext Transfer Protocol.

A especificação moderna de semântica HTTP é a RFC 9110. HTTP é um protocolo de aplicação sem estado: cada requisição deve conter informação suficiente para ser interpretada, embora sistemas possam manter estado por sessões, bancos e outros mecanismos.

5.1 HTTP define

métodos;
campos de cabeçalho;
status;
cache;
negociação de conteúdo;
semântica de requisições e respostas.

5.2 HTTPS

HTTPS é HTTP sobre TLS.

TLS ajuda a garantir:

confidencialidade durante o transporte;
integridade da comunicação;
autenticação do servidor;
opcionalmente, autenticação do cliente por certificado.

HTTPS não impede:

senha fraca;
autorização incorreta;
SQL Injection;
vazamento no banco;
segredo publicado no GitHub;
lógica de negócio vulnerável.

5.3 HTTP/1.1, HTTP/2 e HTTP/3

HTTP/1.1: amplamente compatível; conexões e mensagens textuais.
HTTP/2: multiplexação e compressão de headers.
HTTP/3: utiliza QUIC sobre UDP e integra TLS ao transporte.

A aplicação normalmente usa a mesma semântica de métodos e status, enquanto servidores, proxies e bibliotecas negociam a versão.

6. Anatomia de uma requisição

Exemplo:

POST /v1/ordens-servico?notificar=true HTTP/1.1
Host: api.empresa.com
Authorization: Bearer eyJ...
Content-Type: application/json
Accept: application/json
Idempotency-Key: 3d2d9a40-...
X-Request-ID: 6bf21...

{
  "equipamentoId": 15,
  "descricao": "Inspecionar aquecimento",
  "prioridade": "alta"
}

6.1 Método

POST

Indica a intenção da operação.

6.2 Caminho

/v1/ordens-servico

Identifica o recurso ou operação.

6.3 Query parameter

?notificar=true

Controla filtro ou comportamento.

6.4 Headers

Metadados da comunicação.

6.5 Body

Dados da operação.

6.6 Host

Domínio de destino.

6.7 Content-Type

Formato do conteúdo enviado.

Content-Type: application/json

6.8 Accept

Formato de resposta esperado.

Accept: application/json

6.9 Authorization

Credencial enviada.

Authorization: Bearer TOKEN

6.10 Correlation ID ou Request ID

Identificador usado para rastrear a chamada entre sistemas.

X-Request-ID: 6bf21...

O nome pode variar. Padrões de rastreamento distribuído também usam traceparent.

7. Anatomia de uma resposta

HTTP/1.1 201 Created
Content-Type: application/json
Location: /v1/ordens-servico/101
X-Request-ID: 6bf21...

{
  "id": 101,
  "status": "aberta",
  "criadaEm": "2026-08-01T23:00:00-03:00"
}

7.1 Status HTTP

201 Created

Resultado geral da operação.

7.2 Headers de resposta

Podem informar:

formato;
cache;
localização;
paginação;
limite de chamadas;
cookies;
políticas de segurança;
rastreamento.

7.3 Body

Contém o recurso, resultado ou erro.

8. Métodos HTTP

8.1 GET

Consulta uma representação.

GET /v1/ordens-servico/101

Em geral:

não deve alterar estado de negócio;
é considerado seguro;
pode ser cacheável;
deve ser repetível sem efeitos colaterais de negócio.

8.2 POST

Cria recurso ou executa comando não naturalmente idempotente.

POST /v1/ordens-servico

Repetir pode criar duplicidade, por isso operações críticas podem exigir chave de idempotência.

8.3 PUT

Substitui o recurso inteiro em um endereço conhecido ou cria naquele endereço, dependendo do contrato.

PUT /v1/usuarios/10

É semanticamente idempotente: repetir a mesma operação deve deixar o estado final equivalente.

8.4 PATCH

Altera parcialmente.

PATCH /v1/ordens-servico/101

Pode ou não ser idempotente, conforme a operação.

Exemplo idempotente:

{ "status": "concluida" }

Exemplo potencialmente não idempotente:

{ "incrementarTentativas": 1 }

8.5 DELETE

Solicita remoção.

DELETE /v1/ordens-servico/101

É considerado idempotente quanto ao estado final, mesmo que a primeira resposta seja 204 e a segunda 404.

8.6 HEAD

Retorna headers que seriam associados a um GET, sem corpo.

8.7 OPTIONS

Informa opções de comunicação e é usado em fluxos CORS.

8.8 Segurança e idempotência

Método	Seguro	Normalmente idempotente
GET	Sim	Sim
HEAD	Sim	Sim
OPTIONS	Sim	Sim
PUT	Não	Sim
DELETE	Não	Sim
POST	Não	Não
PATCH	Não	Depende

“Seguro” aqui significa não solicitar alteração de estado; não significa proteção contra ataques.

9. Códigos de status

9.1 1xx — informação

Pouco vistos diretamente em aplicações comuns.

9.2 2xx — sucesso

200 OK: sucesso geral.
201 Created: recurso criado.
202 Accepted: aceito para processamento posterior.
204 No Content: sucesso sem corpo.
206 Partial Content: conteúdo parcial.

9.3 3xx — redirecionamento e cache

301 Moved Permanently;
302 Found;
303 See Other;
304 Not Modified;
307 Temporary Redirect;
308 Permanent Redirect.

9.4 4xx — solicitação, autenticação ou regra

400 Bad Request: requisição inválida.
401 Unauthorized: autenticação ausente ou inválida.
403 Forbidden: autenticado, mas sem permissão.
404 Not Found: recurso não encontrado ou ocultado.
405 Method Not Allowed: método não permitido.
409 Conflict: conflito de estado.
412 Precondition Failed: pré-condição falhou.
413 Content Too Large: payload excedeu limite.
415 Unsupported Media Type: formato não suportado.
422 Unprocessable Content: validação semântica falhou.
429 Too Many Requests: limite excedido.

9.5 5xx — servidor ou dependência

500 Internal Server Error;
501 Not Implemented;
502 Bad Gateway;
503 Service Unavailable;
504 Gateway Timeout.

9.6 O status não substitui o corpo de erro

{
  "type": "https://api.empresa.com/problemas/ordem-fechada",
  "title": "A ordem já está encerrada",
  "status": 409,
  "detail": "A ordem 101 foi encerrada em 2026-08-01.",
  "instance": "/v1/ordens-servico/101",
  "code": "OS_ALREADY_CLOSED",
  "requestId": "6bf21..."
}

10. JSON e outros formatos

10.1 JSON

JSON é um formato textual e independente de linguagem para troca de dados.

{
  "id": 101,
  "nome": "Gerador",
  "ativo": true,
  "potenciaKva": 2000,
  "tags": ["emergencia", "diesel"],
  "localizacao": {
    "setor": "Sala de geradores"
  }
}

Tipos básicos:

string;
number;
boolean;
null;
array;
object.

Limitações do JSON

JSON não possui tipos nativos específicos para:

data;
hora;
decimal financeiro;
binário;
inteiro de precisão arbitrária.

O contrato precisa definir convenções.

Exemplo de data:

"criadaEm": "2026-08-01T23:00:00-03:00"

10.2 YAML

Muito usado em configuração e especificações.

id: 101
nome: Gerador
ativo: true

É amigável para humanos, mas possui detalhes de indentação e parsing que exigem cuidado.

10.3 XML

Ainda comum em:

SOAP;
ERPs;
sistemas fiscais;
integrações legadas;
documentos assinados.

10.4 CSV

Adequado para troca tabular simples e lotes.

Problemas:

tipos pouco explícitos;
diferenças de separador;
encoding;
campos com quebra de linha;
relações complexas.

10.5 Protocol Buffers

Formato binário com contrato tipado, usado frequentemente com gRPC.

Vantagens:

compacto;
rápido;
geração de código;
contrato explícito.

Desvantagens:

menos legível;
exige ferramentas;
maior disciplina de evolução do schema.

10.6 Multipart/form-data

Usado para envio de arquivos e formulários.

10.7 Regra prática

API pública e web comum: JSON.
Integração corporativa legada: XML pode ser obrigatório.
Alto desempenho interno e contratos tipados: Protobuf/gRPC.
Eventos: JSON, Avro ou Protobuf, conforme ecossistema.
Lotes tabulares: CSV, Parquet ou arquivos específicos.

11. Quantidade de chamadas, registros, bytes e tokens

Esta é uma distinção essencial.

11.1 Requisição não é registro

GET /usuarios

Pode ser uma requisição que retorna 10 usuários.

GET /ordens-servico

Pode ser uma requisição que retorna 1.000 ordens.

Na contagem simples de requisições, ambas podem valer uma chamada. Porém, o custo computacional é diferente.

11.2 O que muda ao retornar 1.000 registros

Pode aumentar:

consulta ao banco;
CPU;
memória;
tempo de serialização;
tamanho da resposta;
tráfego;
latência;
custo de nuvem;
tempo de renderização;
risco de timeout;
exposição de dados;
impacto em outros usuários.

11.3 Como uma API pode contabilizar uso

Cada provedor escolhe seu modelo:

requisições por minuto;
requisições por segundo;
operações por dia;
registros processados;
bytes transferidos;
duração computacional;
concorrência;
unidades de leitura/escrita;
tokens de IA;
chamadas de ferramenta;
custo financeiro;
combinação desses fatores.

11.4 Rate limit

É o limite de velocidade.

Exemplo:

100 requisições por minuto

11.5 Quota

É o limite acumulado.

Exemplo:

50.000 chamadas por mês

11.6 Concurrency limit

Limita requisições simultâneas.

11.7 AI token não é token de autenticação

Token de autenticação:

credencial para acessar a API

Token de linguagem:

unidade em que um modelo processa texto

São conceitos completamente diferentes.

11.8 Exemplo de IA

Uma única chamada pode consumir:

Entrada: 5.000 tokens
Saída: 1.000 tokens
Total: 6.000 tokens

Outra chamada curta pode consumir 100 tokens. Ambas são uma requisição, mas têm custos diferentes.

11.9 Boa prática

Nunca crie endpoint “retornar tudo” sem avaliar:

volume máximo;
paginação;
autorização;
campos necessários;
exportação assíncrona;
filtros;
limites;
impacto no banco.

12. Paginação, filtros, ordenação e busca

12.1 Paginação por offset

GET /v1/ordens-servico?page=2&pageSize=50

ou:

GET /v1/ordens-servico?offset=50&limit=50

Vantagens:

simples;
fácil de exibir páginas.

Desvantagens:

pode ficar lenta em grandes offsets;
registros inseridos durante a navegação podem gerar duplicidade ou omissão.

12.2 Paginação por cursor

GET /v1/ordens-servico?limit=50&after=eyJpZCI6MTAwfQ

Resposta:

{
  "items": [],
  "nextCursor": "eyJpZCI6MTUwfQ",
  "hasMore": true
}

Vantagens:

melhor para grandes volumes;
mais estável em dados mutáveis.

12.3 Filtros

GET /v1/ordens-servico?status=aberta&prioridade=alta

12.4 Ordenação

GET /v1/ordens-servico?sort=-criadaEm,prioridade

A convenção deve ser documentada.

12.5 Busca

GET /v1/ordens-servico?q=transformador

Busca textual é diferente de filtros exatos.

12.6 Seleção de campos

GET /v1/ordens-servico?fields=id,status,responsavel

Pode reduzir payload, mas aumenta complexidade.

12.7 Exportações grandes

Para 500 mil registros, pode ser melhor:

POST /exportacoes;
retornar 202 Accepted;
processar em background;
consultar status;
disponibilizar arquivo temporário.

13. Estilos de API

13.1 REST sobre HTTP

Foca em recursos e semântica HTTP.

GET /ordens-servico/101

13.2 RPC

Foca em ações ou procedimentos remotos.

POST /ordens-servico/101/concluir

Não é automaticamente ruim. Comandos de negócio podem ser mais claros como ações explícitas.

13.3 GraphQL

Cliente solicita os campos necessários.

query {
  ordemServico(id: 101) {
    id
    status
    equipamento {
      nome
    }
  }
}

Vantagens:

consulta flexível;
schema tipado;
bom para múltiplas visões de dados.

Riscos:

consultas caras;
autorização por campo;
N+1;
cache mais complexo;
profundidade e complexidade abusivas.

13.4 gRPC

Define serviços e mensagens em Protobuf.

service OrdemService {
  rpc ObterOrdem (ObterOrdemRequest) returns (Ordem);
}

É adequado para:

comunicação interna;
baixa latência;
streaming;
contratos fortemente tipados.

13.5 SOAP

Usa XML e contratos WSDL.

Comum em:

bancos;
governo;
ERPs;
sistemas legados;
integrações formais.

13.6 WebSocket

Conexão bidirecional persistente.

Usado em:

chat;
telemetria;
colaboração;
dados em tempo real.

13.7 Server-Sent Events

Servidor envia eventos continuamente ao navegador em uma direção.

13.8 Webhook

Um sistema chama outro quando ocorre evento.

13.9 Event-driven API

Sistemas publicam e consomem eventos por broker.

13.10 Escolha prática

Necessidade	Opção comum
CRUD público ou corporativo	REST/HTTP
Consultas flexíveis por frontend	GraphQL
Serviço interno de alto desempenho	gRPC
Legado corporativo formal	SOAP
Notificação de evento entre sistemas	Webhook
Alto volume e desacoplamento	Broker/eventos
Atualização contínua navegador	SSE/WebSocket

14. REST sem mitologia

REST foi descrito por Roy Fielding em sua dissertação de 2000 como um estilo arquitetural para sistemas distribuídos baseados em hipermídia.

Em projetos comerciais, “REST API” frequentemente significa:

HTTP;
URLs de recursos;
JSON;
métodos HTTP;
status HTTP.

Isso pode ser útil, mas não garante aderência completa às restrições originais de REST.

14.1 Restrições clássicas

cliente-servidor;
stateless;
cache;
interface uniforme;
sistema em camadas;
código sob demanda opcional.

14.2 HATEOAS

Hipermídia orienta transições.

{
  "id": 101,
  "status": "aberta",
  "_links": {
    "self": { "href": "/ordens-servico/101" },
    "concluir": { "href": "/ordens-servico/101/concluir" }
  }
}

Muitas APIs chamadas REST não implementam hipermídia. Isso não impede que sejam úteis, mas convém usar os termos com precisão.

15. Contrato e documentação

Uma API profissional precisa de documentação legível por pessoas e, quando possível, por máquinas.

15.1 OpenAPI

OpenAPI descreve APIs HTTP de forma independente de linguagem.

Na data deste manual, a versão publicada mais recente é OpenAPI 3.2.0, de setembro de 2025.

Pode descrever:

servidores;
caminhos;
métodos;
parâmetros;
schemas;
autenticação;
exemplos;
respostas;
erros;
webhooks.

15.2 Swagger

Swagger é um ecossistema de ferramentas historicamente ligado à especificação que se tornou OpenAPI.

Termos comuns:

Swagger UI;
Swagger Editor;
Swagger Codegen;
OpenAPI Specification.

“Swagger” e “OpenAPI” não são exatamente sinônimos.

15.3 JSON Schema

Define estrutura, tipos e restrições de documentos JSON.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["equipamentoId", "descricao"],
  "properties": {
    "equipamentoId": {
      "type": "integer",
      "minimum": 1
    },
    "descricao": {
      "type": "string",
      "minLength": 10,
      "maxLength": 500
    }
  },
  "additionalProperties": false
}

15.4 AsyncAPI

Descreve APIs orientadas a mensagens e eventos.

Na data deste manual, a versão publicada indicada pelo projeto é 3.1.0.

15.5 Protobuf

Contrato para gRPC e mensagens binárias.

15.6 GraphQL SDL

Define tipos e operações de um schema GraphQL.

15.7 Arazzo

Especificação da OpenAPI Initiative para descrever sequências e workflows de chamadas. A versão 1.1.0 foi publicada em maio de 2026.

15.8 O que a documentação deve conter

finalidade;
ambiente;
base URL;
autenticação;
endpoints;
parâmetros;
schemas;
exemplos;
status;
regras de negócio;
limites;
paginação;
versionamento;
idempotência;
webhooks;
erros;
SLA;
contato de suporte;
changelog;
depreciação.

16. Design-first, code-first e API-first

16.1 Code-first

O código é implementado e a documentação é gerada a partir dele.

Vantagens:

rapidez inicial;
aderência direta à implementação.

Riscos:

contrato vira consequência do código;
decisões inconsistentes;
documentação incompleta;
consumidores descobrem problemas tarde.

16.2 Design-first

O contrato é desenhado antes da implementação.

Fluxo:

requisitos;
modelo;
OpenAPI;
revisão;
mock;
implementação;
testes de contrato.

Vantagens:

alinhamento antecipado;
frontend e backend podem trabalhar em paralelo;
menos retrabalho.

16.3 API-first

APIs são tratadas como produtos e contratos centrais da arquitetura.

Inclui:

governança;
catálogo;
padrões;
ownership;
versionamento;
experiência do consumidor;
observabilidade;
segurança.

16.4 Recomendação

Para integração relevante:

desenhar contrato antes;
revisar com consumidores;
criar exemplos;
validar segurança;
gerar mock;
implementar;
verificar aderência automaticamente.

17. Boas práticas de desenho de endpoints

17.1 Use nomes do domínio

Bom:

/ordens-servico
/equipamentos
/medidores

Evite URLs baseadas em detalhes de tela:

/telaOS
/botaoConcluir

17.2 Consistência vale mais que preferência pessoal

Escolha convenções e aplique em toda a API:

singular ou plural;
camelCase ou snake_case;
formato de datas;
paginação;
erros;
filtros;
IDs.

17.3 Não exponha estrutura de banco

Evite endpoint que reflita diretamente tabelas sem considerar o domínio.

17.4 Campos de entrada e saída separados

O cliente não deve poder enviar propriedades administrativas apenas porque elas aparecem na resposta.

Entrada:

{
  "descricao": "Falha no ventilador"
}

Saída:

{
  "id": 101,
  "descricao": "Falha no ventilador",
  "criadaPor": "usuario-123",
  "criadaEm": "..."
}

17.5 Valide allowlist

Defina explicitamente campos aceitos.

Isso reduz mass assignment.

17.6 Datas

Prefira ISO 8601/RFC 3339 com timezone.

2026-08-01T23:55:00-03:00

17.7 Valores monetários

Evite ponto flutuante sem definição.

{
  "valorCentavos": 129900,
  "moeda": "BRL"
}

ou decimal documentado como string.

17.8 IDs

Podem ser:

inteiros;
UUID;
ULID;
identificadores opacos.

Um ID não é mecanismo de autorização.

17.9 Operações longas

Use 202 Accepted e recurso de acompanhamento.

17.10 Operações em lote

Defina:

limite;
atomicidade;
resposta por item;
repetição;
idempotência;
tratamento de falha parcial.

18. Erros padronizados

A RFC 9457 define Problem Details for HTTP APIs.

Exemplo:

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://api.empresa.com/problems/validation-error",
  "title": "Dados inválidos",
  "status": 422,
  "detail": "Um ou mais campos são inválidos.",
  "instance": "/v1/ordens-servico",
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "field": "descricao",
      "message": "Deve possuir pelo menos 10 caracteres."
    }
  ],
  "requestId": "6bf21..."
}

18.1 Não exponha

stack trace;
SQL;
senha;
segredo;
caminho interno;
nome de servidor desnecessário;
detalhes que auxiliem ataque.

18.2 Separe

mensagem para usuário;
código estável para sistema;
detalhe técnico em log;
ID de correlação.

18.3 O código de erro de negócio deve ser estável

OS_ALREADY_CLOSED

é melhor para automação que depender de uma frase humana.

19. Versionamento e compatibilidade

19.1 Estratégias

Caminho

/v1/ordens-servico

Header

Accept: application/vnd.empresa.v1+json

Query

?api-version=2026-08-01

Cada abordagem tem vantagens e custos.

19.2 Mudança compatível

Normalmente:

adicionar campo opcional;
adicionar endpoint;
ampliar enum com cuidado;
adicionar parâmetro opcional.

19.3 Mudança incompatível

remover campo;
renomear campo;
mudar tipo;
alterar significado;
tornar opcional obrigatório;
mudar autorização;
alterar status esperado.

19.4 Atenção aos enums

Adicionar novo valor pode quebrar clientes que usam switch fechado.

19.5 Política de depreciação

Defina:

aviso;
prazo;
versão substituta;
telemetria de consumidores;
documentação;
contato;
data de desligamento.

19.6 Contrato não é só JSON

Também são contrato:

status;
ordem;
comportamento;
autenticação;
limites;
latência;
consistência;
erros.

20. Idempotência, concorrência e consistência

20.1 Idempotency-Key

Em pagamentos, criação de pedidos ou comandos críticos:

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

O servidor registra a chave e devolve o mesmo resultado para repetição equivalente.

20.2 Problema evitado

Cliente envia criação, perde a resposta e repete. Sem idempotência, dois registros podem ser criados.

20.3 Concorrência otimista com ETag

Resposta:

ETag: "versao-7"

Atualização:

If-Match: "versao-7"

Se outra pessoa já alterou, o servidor pode retornar:

412 Precondition Failed

20.4 Transações

Operações que precisam ser atômicas devem usar transação no banco ou estratégia distribuída apropriada.

20.5 Consistência eventual

Em sistemas distribuídos, atualizações podem não aparecer imediatamente em todos os componentes.

Isso precisa ser documentado.

20.6 Retries

Repetições automáticas devem considerar:

idempotência;
timeout;
backoff exponencial;
jitter;
limite;
status transitórios;
Retry-After.

Não repita indiscriminadamente POST não idempotente.

21. Cache, compressão e desempenho

21.1 Cache-Control

Cache-Control: private, max-age=60

21.2 ETag e 304

Cliente envia:

If-None-Match: "abc"

Servidor pode responder:

304 Not Modified

21.3 Dados sensíveis

Não permita cache público inadequado.

21.4 Compressão

Pode usar gzip ou Brotli conforme suporte.

Compressão reduz bytes, mas consome CPU e pode criar riscos em determinados cenários com segredos refletidos.

21.5 N+1

O backend faz uma consulta principal e outra para cada registro.

Exemplo:

1 consulta de ordens + 1.000 consultas de equipamentos

Pode ser resolvido com:

joins;
batch loading;
DataLoader;
modelagem adequada;
cache.

21.6 Índices de banco

Filtros e ordenações frequentes podem exigir índices.

21.7 Medir antes de otimizar

Métricas importantes:

p50;
p95;
p99;
throughput;
taxa de erro;
saturação;
tempo de banco;
tamanho de payload.

22. Autenticação e autorização

22.1 Autenticação

Responde:

Quem é o usuário ou aplicação?

22.2 Autorização

Responde:

Essa identidade pode realizar esta ação sobre este recurso?

22.3 Identificação não basta

O usuário 10 pode estar autenticado, mas não deve acessar a ordem pertencente ao usuário 11.

22.4 Modelos de autorização

RBAC

Baseado em papéis.

eletricista
supervisor
administrador

ABAC

Baseado em atributos.

departamento == manutenção
e unidade == Fortaleza
e turno == ativo

ReBAC

Baseado em relações.

usuário é responsável pela ordem

ACL

Lista de permissões por recurso.

22.5 Regra essencial

Autorização deve ser aplicada:

em cada endpoint;
em cada objeto;
em cada propriedade sensível;
em cada função administrativa;
no backend.

23. Sessões e cookies

23.1 Sessão server-side

O servidor mantém estado:

session_id → usuário, permissões, validade

O navegador recebe um identificador em cookie.

23.2 Cookie

Exemplo:

Set-Cookie: session_id=abc; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=3600

23.3 HttpOnly

Impede leitura direta pelo JavaScript do navegador.

Ajuda contra roubo de cookie por certos ataques XSS, mas não impede o navegador de enviá-lo em chamadas.

23.4 Secure

Cookie só é enviado por HTTPS.

23.5 SameSite

Controla envio em contexto entre sites.

Strict: mais restritivo.
Lax: equilíbrio comum.
None: permite contexto cross-site e exige Secure.

23.6 Domain

Define domínio aplicável. Evite ampliar desnecessariamente.

23.7 Path

Restringe caminho.

23.8 Max-Age e Expires

Controlam persistência.

23.9 Quem configura

Normalmente:

backend;
framework de autenticação;
proxy;
equipe de plataforma.

Frontend não deve armazenar manualmente cookie de sessão sensível em JavaScript.

23.10 Timeouts

idle timeout: expira por inatividade;
absolute timeout: expira mesmo com atividade;
renewal timeout: renova identificador durante a sessão.

24. Tokens: conceitos e ciclo de vida

24.1 O que é token

É uma credencial ou artefato que representa autorização, identidade ou estado.

24.2 Quem gera

Normalmente:

servidor de autenticação;
provedor de identidade;
backend;
serviço de autorização.

O frontend não deve inventar um token e esperar que a API confie nele.

24.3 Fluxo prático

Usuário fornece credencial
        ↓
Servidor autentica
        ↓
Servidor gera token
        ↓
Aplicativo recebe
        ↓
Aplicativo envia token à API
        ↓
API valida

24.4 Access token

Usado para acessar API.

24.5 Refresh token

Usado para obter novo access token.

24.6 ID token

Informa identidade ao cliente OpenID Connect.

24.7 API key

Identifica aplicação ou projeto; não é igual a access token OAuth.

24.8 Token opaco

String sem significado para o cliente. A API consulta ou introspecta no servidor.

24.9 Token auto-contido

Carrega claims verificáveis, como JWT.

24.10 Quando o access token expira

Possibilidades:

a API responde 401;
o cliente usa refresh token;
recebe novo access token;
repete a operação;
se refresh falhar ou expirar, exige login.

24.11 Usuário ativo não significa token eterno

Um sistema pode renovar silenciosamente enquanto:

refresh token estiver válido;
sessão estiver ativa;
políticas permitirem;
risco não exigir reautenticação.

Ainda assim, deve existir limite absoluto ou política de reautenticação.

24.12 Logout

Logout deve considerar:

apagar cookie;
invalidar sessão;
revogar refresh token;
encerrar sessões relevantes;
lidar com access token ainda válido.

JWT auto-contido pode continuar válido até expirar, salvo mecanismo de revogação, introspecção ou rotação.

24.13 Armazenamento

Em navegador:

cookie HttpOnly costuma ser preferível para sessão;
localStorage é acessível por JavaScript e aumenta impacto de XSS;
não existe solução universal sem análise arquitetural.

Em mobile:

Keychain;
Keystore;
armazenamento seguro da plataforma.

Em backend:

secret manager;
memória;
armazenamento criptografado;
nunca logar token completo.

25. JWT explicado campo por campo

JWT significa JSON Web Token.

Estrutura:

header.payload.signature

Cada parte é codificada em Base64URL.

25.1 Header

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "chave-2026-01"
}

alg: algoritmo.
typ: tipo.
kid: identificador da chave.

25.2 Payload

{
  "iss": "https://login.empresa.com",
  "sub": "usuario-123",
  "aud": "api-manutencao",
  "iat": 1785632400,
  "nbf": 1785632400,
  "exp": 1785633300,
  "jti": "token-456",
  "scope": "os:read os:write",
  "role": "supervisor"
}

iss: emissor.
sub: sujeito.
aud: destinatário.
iat: emitido em.
nbf: válido a partir de.
exp: expiração.
jti: identificador do token.
scope: escopos.
claims customizadas: papel, tenant etc.

25.3 Signature

Protege integridade e autenticidade.

25.4 Assinado não significa criptografado

Payload pode ser lido.

Não coloque:

senha;
segredo;
dado pessoal desnecessário;
informação que não possa aparecer no cliente ou em logs.

25.5 Validações obrigatórias

A API deve validar, conforme o contrato:

assinatura;
algoritmo permitido;
emissor;
público;
expiração;
nbf;
tipo de token;
escopo;
chave confiável;
contexto do recurso.

25.6 Falhas comuns

aceitar alg=none;
confiar no algoritmo declarado sem allowlist;
não validar aud;
não validar iss;
aceitar token expirado;
usar segredo fraco em HMAC;
confundir ID token com access token;
colocar permissões permanentes em token longo;
logar token;
guardar em local inseguro;
não rotacionar chaves;
não planejar revogação.

25.7 Não “decodifique” e confie

Decodificar Base64URL não prova autenticidade.

Errado:

const payload = JSON.parse(atob(token.split(".")[1]));
// usar role como verdade

Correto:

usar biblioteca madura;
verificar assinatura;
validar claims;
configurar algoritmos;
tratar falhas.

26. OAuth 2.0, OAuth 2.1 e OpenID Connect

26.1 OAuth 2.0

Framework de autorização delegada.

Permite que uma aplicação obtenha acesso limitado:

em nome de usuário;
ou em nome da própria aplicação.

26.2 Papéis

Resource Owner;
Client;
Authorization Server;
Resource Server.

26.3 Authorization Code com PKCE

Fluxo recomendado em muitos clientes modernos.

Cliente gera code_verifier
       ↓
deriva code_challenge
       ↓
redireciona usuário ao Authorization Server
       ↓
usuário autentica
       ↓
cliente recebe authorization code
       ↓
troca code + verifier por tokens

PKCE reduz risco de interceptação do código.

26.4 Client Credentials

Sistema com sistema.

serviço → authorization server → access token → API

Não representa usuário humano.

26.5 Device Authorization Grant

Útil para dispositivos com entrada limitada.

26.6 Fluxos que não devem ser escolhidos por legado automático

Implicit Grant: depreciado nas boas práticas modernas.
Resource Owner Password Credentials: não deve ser usado em novos projetos.

26.7 RFC 9700

A RFC 9700, publicada em 2025, consolida boas práticas atuais de segurança OAuth 2.0.

26.8 OAuth 2.1

Na data deste manual, OAuth 2.1 permanece um Internet-Draft, não um RFC final. Ele consolida OAuth 2.0 e práticas modernas, removendo fluxos inseguros ou obsoletos.

Não diga “seguimos OAuth 2.1 final” sem verificar o status atual.

26.9 OpenID Connect

Camada de identidade sobre OAuth 2.0.

OAuth 2.0 → autorização
OIDC      → autenticação federada e identidade

26.10 Scope

Permissão delegada.

os.read
os.write
profile
email

26.11 Consentimento

O usuário pode autorizar determinadas permissões.

26.12 State e nonce

Usados para proteção e correlação em fluxos adequados.

26.13 Redirect URI

Deve ser validada estritamente. Redirects abertos permitem roubo de código ou token.

27. SSO, SAML, LDAP, Active Directory e Kerberos

27.1 SSO

Single Sign-On é a experiência de autenticar uma vez e acessar vários sistemas.

Não é um protocolo único.

27.2 SAML

Padrão XML para federação corporativa.

Partes:

Identity Provider;
Service Provider;
Assertion.

27.3 LDAP

Protocolo de acesso a diretórios.

Pode consultar:

usuários;
grupos;
departamentos;
computadores;
atributos.

27.4 Active Directory

Produto/serviço da Microsoft para identidade e recursos de domínio.

Pode usar:

LDAP;
Kerberos;
DNS;
Group Policy.

27.5 Microsoft Entra ID

Serviço de identidade em nuvem, anteriormente Azure Active Directory. Não é simplesmente o mesmo que Active Directory local.

27.6 Kerberos

Autenticação por tickets, comum em domínio Windows.

27.7 Relação prática

Active Directory → diretório corporativo local
LDAP            → protocolo de consulta
Kerberos        → protocolo de autenticação
SAML/OIDC       → federação com aplicações
SSO             → experiência resultante

28. Hash de senha

28.1 O que é

Hash de senha é uma transformação unidirecional usada para verificar senha sem armazená-la em texto puro.

28.2 Fluxo de cadastro

senha digitada
   ↓
algoritmo de password hashing + salt
   ↓
hash
   ↓
banco

28.3 Fluxo de login

senha informada
   ↓
verificação usando parâmetros armazenados
   ↓
comparação segura

28.4 Salt

Valor aleatório único por senha.

Impede que senhas iguais gerem necessariamente hashes iguais e dificulta tabelas pré-computadas.

Salt normalmente é armazenado junto do hash.

28.5 Pepper

Segredo adicional mantido fora do banco, por exemplo em secret manager. É opcional e exige estratégia operacional.

28.6 Algoritmos apropriados

A OWASP recomenda algoritmos de password hashing lentos e resistentes a hardware paralelo, como:

Argon2id;
scrypt;
bcrypt em legado;
PBKDF2 quando exigido por contexto específico.

28.7 Não usar para senha

MD5;
SHA-1;
SHA-256 puro;
criptografia reversível;
Base64.

SHA-256 é excelente em outras finalidades, mas rápido demais para armazenar senha sozinho.

28.8 Quem configura

arquiteto e segurança definem requisito;
backend implementa biblioteca;
DevOps fornece secret manager se houver pepper;
DBA protege banco;
QA testa;
segurança valida parâmetros e fluxo.

28.9 Não implemente algoritmo próprio

Use biblioteca madura e atualizada.

28.10 Rehash progressivo

Ao fazer login, o sistema pode atualizar hash antigo para parâmetros modernos.

28.11 Recuperação de senha

Senha não é “descriptografada”. O sistema gera fluxo de redefinição com token temporário, uso único e seguro.

29. Quem configura cada componente

Item	Responsável primário	Participação
Regras de negócio	Produto/negócio	Backend, QA
Contrato da API	Arquiteto/backend	Frontend, consumidores
OpenAPI	Backend/API designer	QA, frontend
Endpoints	Backend	Arquiteto
Banco e índices	Backend/DBA	Dados, infraestrutura
TLS/HTTPS	Plataforma/DevOps	Segurança, rede
DNS	Infraestrutura/rede	Plataforma
Firewall/WAF	Segurança/rede	Plataforma
Cookies	Backend	Segurança, frontend
`HttpOnly`/`Secure`/`SameSite`	Backend/plataforma	Segurança
Geração de token	IdP/backend	IAM, segurança
Validação de token	Backend/gateway	IAM, segurança
OAuth/OIDC	IAM/arquitetura	Backend, frontend
Active Directory	IAM/infraestrutura	Segurança
Perfis e permissões	Negócio + IAM/backend	Segurança
API keys	Plataforma/provedor	DevOps, segurança
Secret manager	DevOps/plataforma	Segurança
CORS	Backend/gateway	Frontend, segurança
Rate limiting	Gateway/backend	Plataforma
Logs	Backend/plataforma	Segurança, operação
Métricas e tracing	Plataforma/backend	SRE
Testes funcionais	QA/backend	Frontend
Testes de segurança	AppSec/pentest	Desenvolvimento
Backup	DBA/plataforma	Negócio
Retenção/LGPD	Jurídico/privacidade	Produto, segurança
SLA/SLO	Negócio + SRE	Arquitetura
Aprovação de produção	Governança	Donos do sistema

A responsabilidade varia por organização, mas não deve ficar implícita.

30. OWASP API Security Top 10

A edição mais recente publicada do OWASP API Security Top 10 na data deste manual é a de 2023.

API1 — Broken Object Level Authorization

Usuário altera ID e acessa objeto de outro usuário.

GET /contas/123

Troca para:

GET /contas/124

Controle:

verificar autorização por objeto;
não confiar em ID;
testes negativos.

API2 — Broken Authentication

Falhas em login, tokens e sessões.

Controles:

biblioteca madura;
MFA;
rate limit;
expiração;
rotação;
revogação;
validação completa.

API3 — Broken Object Property Level Authorization

Exposição ou alteração indevida de campos.

Exemplo:

{
  "nome": "Cleiton",
  "role": "admin"
}

Controle:

DTOs separados;
allowlist;
autorização por campo;
não serializar tudo.

API4 — Unrestricted Resource Consumption

Chamadas consomem recursos excessivos.

Controles:

paginação;
limites;
timeout;
quota;
custo máximo;
upload limitado;
proteção contra consultas caras.

API5 — Broken Function Level Authorization

Usuário comum acessa endpoint administrativo.

DELETE /admin/usuarios/10

Controle:

autorização no backend;
política central;
teste por função.

API6 — Unrestricted Access to Sensitive Business Flows

Automação abusa de fluxo legítimo.

Exemplos:

compra de estoque;
criação de contas;
reserva;
envio de cupom;
votação.

Controles:

anti-automação;
limites;
detecção;
confirmação;
análise de negócio.

API7 — Server Side Request Forgery

Servidor busca URL controlada pelo atacante.

Controles:

allowlist;
bloquear rede interna e metadata;
resolver DNS com segurança;
limitar protocolo;
proxy de saída.

API8 — Security Misconfiguration

CORS aberto;
debug em produção;
headers ausentes;
credenciais padrão;
métodos desnecessários;
erros detalhados.

API9 — Improper Inventory Management

APIs esquecidas, versões antigas e ambientes expostos.

Controles:

catálogo;
ownership;
descoberta;
depreciação;
inventário de domínios e rotas.

API10 — Unsafe Consumption of APIs

Confiar cegamente em dados de terceiros.

Controles:

validar resposta;
timeout;
schema;
limites;
sanitização;
isolamento;
autenticar fornecedor.

31. Segurança por camada

31.1 Frontend

Riscos:

XSS;
segredo embutido;
token em local inseguro;
dependência comprometida;
CORS mal compreendido;
exposição de dados;
validação apenas no cliente.

Controles:

não inserir segredos;
Content Security Policy;
encoding de saída;
sanitização quando necessária;
dependências controladas;
backend como autoridade;
evitar dados desnecessários.

31.2 Backend

Riscos:

autorização quebrada;
injeção;
SSRF;
deserialização insegura;
mass assignment;
erro revelador;
timeout ausente;
falha aberta.

Controles:

validação por schema;
queries parametrizadas;
allowlists;
políticas de acesso;
limites;
tratamento de exceção;
logs estruturados;
testes negativos.

31.3 Banco

Riscos:

SQL Injection;
conta com privilégio excessivo;
banco público;
backup exposto;
criptografia inadequada;
falta de auditoria;
multi-tenant mal isolado.

Controles:

prepared statements;
menor privilégio;
segmentação;
criptografia;
backup;
teste de restauração;
políticas por linha quando apropriado;
revisão de migrations.

31.4 Infraestrutura

Riscos:

portas expostas;
TLS fraco;
segredo em variável pública;
container privilegiado;
permissões cloud amplas;
storage público;
ausência de patch.

Controles:

IaC revisada;
hardening;
segmentação;
patching;
secret manager;
IAM mínimo;
scanning;
inventário.

31.5 CI/CD

Riscos:

segredo no log;
runner comprometido;
pacote malicioso;
action não fixada;
artefato adulterado;
agente com permissão excessiva.

Controles:

branch protection;
revisão;
assinatura;
SBOM;
SAST;
SCA;
secret scanning;
ambientes protegidos;
credenciais temporárias;
provenance.

31.6 Logs

Nunca registrar integralmente:

senha;
access token;
refresh token;
API key;
cartão;
documento pessoal sem necessidade;
corpo sensível.

Registrar:

request ID;
evento;
usuário ou serviço;
resultado;
latência;
origem relevante;
decisão de autorização;
sem segredo.

31.7 Segurança por design

Referências atuais:

OWASP ASVS 5.0.0;
OWASP Top 10 2025;
OWASP API Security Top 10 2023;
NIST SSDF 1.1 final;
NIST SSDF 1.2 ainda em rascunho inicial na data deste manual;
CISA Secure by Design.

32. Riscos do desenvolvimento assistido por IA

Ferramentas de IA aceleram desenvolvimento, mas não eliminam responsabilidade técnica.

32.1 Falhas frequentes

inventar biblioteca;
usar método depreciado;
gerar autenticação incompleta;
criar endpoint sem autorização;
colocar chave no frontend;
aceitar qualquer origem CORS;
montar SQL por concatenação;
remover teste para “ficar verde”;
criar migration destrutiva;
instalar pacote desconhecido;
registrar dados sensíveis;
copiar código incompatível;
usar versão errada da documentação.

32.2 Riscos de agentes

Agentes podem:

executar shell;
ler arquivos;
instalar dependências;
acessar rede;
alterar CI;
fazer commits;
enviar contexto a serviços externos.

32.3 `.gitignore` não protege do agente

Uma ferramenta pode ler .env mesmo que o Git não o envie.

Use mecanismos de exclusão próprios da ferramenta e controle de acesso.

32.4 Regras para vibe coding responsável

Definir objetivo e critérios de aceite.
Não dar acesso desnecessário.
Usar sandbox.
Proteger segredos.
Revisar diff.
Executar testes.
Rodar lint e análise estática.
Verificar dependências.
Validar autenticação e autorização.
Fazer threat modeling.
Não permitir publicação automática irrestrita.
Manter reversão.
Não aceitar “funcionou” sem evidência.

32.5 Prompt injection em agentes

Conteúdo de:

issue;
README;
página web;
documento;
comentário de código;

pode conter instruções maliciosas para o agente.

Controles:

tratar conteúdo externo como dado;
separar instruções;
allowlist de ferramentas;
confirmação para ações críticas;
menor privilégio;
logs;
validação de saída.

32.6 Referências específicas

OWASP Secure Coding with AI Cheat Sheet;
OWASP LLM Prompt Injection Prevention;
OWASP AI Agent Security;
OWASP MCP Security;
NIST SP 800-218A para desenvolvimento de IA;
NIST AI RMF e perfil de IA generativa.

33. Ferramentas para trabalhar com APIs

33.1 Clientes e exploração

cURL

Linha de comando, universal e automatizável.

curl -X GET \
  "https://api.empresa.com/v1/ordens-servico?limit=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/json"

Postman

chamadas;
coleções;
ambientes;
testes;
documentação;
automação;
HTTP, GraphQL e gRPC.

Bruno

local/offline-first;
coleções em texto;
amigável ao Git;
CLI;
testes.

Insomnia

Cliente para APIs e ambientes.

HTTPie

Linha de comando com sintaxe amigável.

Hoppscotch

Cliente web e open source.

33.2 Documentação e design

Swagger UI;
Swagger Editor;
Redocly;
Scalar;
Stoplight;
Postman Spec Hub;
AsyncAPI Studio.

33.3 Lint de especificação

Spectral;
Redocly CLI;
Vacuum;
regras organizacionais customizadas.

33.4 Mock

Prism;
WireMock;
MockServer;
Mock Service Worker;
Postman mock server.

33.5 Teste funcional

Postman/Newman ou Postman CLI;
Bruno CLI;
pytest;
Supertest;
REST Assured;
xUnit/NUnit;
Pact;
Schemathesis.

33.6 Carga e desempenho

k6;
JMeter;
Gatling;
Locust;
Artillery.

33.7 Segurança

OWASP ZAP;
Burp Suite;
Semgrep;
CodeQL;
Trivy;
Grype;
Dependabot;
Renovate;
Gitleaks;
TruffleHog.

33.8 Observabilidade

OpenTelemetry;
Prometheus;
Grafana;
Loki;
Elastic Stack;
Jaeger;
Tempo;
Sentry;
Datadog;
New Relic.

33.9 Regra de escolha

Não adote ferramenta porque é famosa. Avalie:

requisitos;
segurança;
licença;
armazenamento de segredos;
colaboração;
integração com Git;
CI/CD;
suporte;
custo;
exportabilidade;
lock-in.

34. Bibliotecas e frameworks por linguagem

Esta lista apresenta opções conhecidas, não um ranking absoluto.

34.1 JavaScript/TypeScript

Cliente

fetch;
Axios;
Ky;
Undici.

Backend

Node.js HTTP;
Express;
Fastify;
NestJS;
Hono;
Koa.

Validação

Zod;
Joi;
Ajv;
class-validator.

34.2 Python

Cliente

requests;
HTTPX;
aiohttp.

Backend

FastAPI;
Django REST Framework;
Flask;
Litestar.

Validação

Pydantic;
JSON Schema.

34.3 Java/Kotlin

Cliente

Java HttpClient;
Spring RestClient/WebClient;
OkHttp;
Retrofit;
Ktor Client.

Backend

Spring Boot;
Spring MVC/WebFlux;
Jakarta REST;
Quarkus;
Micronaut;
Ktor.

34.4 C#/.NET

Cliente

HttpClient;
Refit.

Backend

ASP.NET Core Controllers;
ASP.NET Core Minimal APIs.

Validação

Data Annotations;
FluentValidation.

34.5 Go

Cliente e servidor

net/http.

Routers/frameworks

Chi;
Gin;
Echo;
Fiber.

34.6 PHP

Cliente

Guzzle.

Backend

Laravel;
Symfony;
API Platform;
Slim.

34.7 Ruby

Rails API;
Sinatra;
Faraday;
HTTP.rb.

34.8 Rust

Reqwest;
Axum;
Actix Web;
Rocket.

34.9 Mobile

Dart/Flutter

http;
Dio.

Android/Kotlin

Retrofit;
OkHttp;
Ktor.

iOS/Swift

URLSession;
Alamofire.

34.10 Critérios de seleção

maturidade;
comunidade;
documentação;
segurança;
tipagem;
desempenho;
observabilidade;
curva de aprendizagem;
compatibilidade da equipe;
manutenção;
número de dependências;
política de atualização.

35. Testes de API

35.1 Teste unitário

Valida função isolada.

35.2 Teste de integração

Valida backend com banco ou dependência real/controlada.

35.3 Teste de contrato

Valida compatibilidade entre produtor e consumidor.

35.4 Teste end-to-end

Valida fluxo completo.

35.5 Teste de componente

Serviço em execução com dependências controladas.

35.6 Teste de carga

Mede comportamento sob volume.

35.7 Teste de resiliência

Simula:

timeout;
indisponibilidade;
latência;
erro;
duplicidade;
perda de mensagem.

35.8 Teste de segurança

Inclui:

autenticação;
autorização;
BOLA;
BFLA;
injeção;
SSRF;
rate limit;
upload;
CORS;
erro;
segredo.

35.9 Casos mínimos por endpoint

sucesso;
campo ausente;
tipo inválido;
valor limite;
não autenticado;
sem permissão;
objeto de outro usuário;
recurso inexistente;
repetição;
concorrência;
dependência indisponível;
payload excessivo.

35.10 Contract testing

Ferramentas como Pact podem verificar se mudanças do produtor quebram consumidores.

35.11 Fuzzing baseado em schema

Ferramentas podem gerar entradas a partir de OpenAPI e procurar falhas.

35.12 Não teste somente happy path

Grande parte das vulnerabilidades aparece nos caminhos de erro, autorização e limites.

36. Observabilidade e operação

36.1 Três pilares

logs;
métricas;
traces.

36.2 Logs estruturados

{
  "timestamp": "2026-08-01T23:55:00-03:00",
  "level": "INFO",
  "event": "order.updated",
  "requestId": "6bf21",
  "userId": "usuario-123",
  "orderId": 101,
  "durationMs": 84
}

36.3 Métricas RED

Rate;
Errors;
Duration.

36.4 Métricas USE

Utilization;
Saturation;
Errors.

36.5 Tracing distribuído

Permite acompanhar:

frontend → gateway → serviço A → serviço B → banco

36.6 SLI, SLO e SLA

SLI: indicador medido.
SLO: objetivo interno.
SLA: compromisso contratual.

36.7 Alertas úteis

taxa de erro;
p95/p99;
saturação;
fila acumulada;
falha de autenticação anormal;
aumento de 401/403;
429;
consumo financeiro;
expiração de certificado;
erro de webhook.

36.8 Health checks

liveness;
readiness;
startup.

Não exponha detalhes sensíveis no health endpoint público.

37. API Gateway e gestão de APIs

Um API Gateway pode centralizar:

roteamento;
autenticação;
rate limiting;
quotas;
TLS;
transformação;
logging;
analytics;
versionamento;
políticas;
monetização.

Exemplos:

Kong;
NGINX;
Envoy;
Traefik;
Apigee;
AWS API Gateway;
Azure API Management;
Cloudflare.

37.1 Gateway não substitui autorização de negócio

Ele pode validar token, mas o serviço ainda precisa decidir:

Este usuário pode alterar esta ordem específica?

37.2 API Management

Pode incluir:

portal de desenvolvedor;
catálogo;
assinatura;
analytics;
ciclo de vida;
planos;
documentação;
políticas;
produtos de API.

37.3 Quando não usar

Projeto pequeno pode começar com proxy simples e backend bem desenhado.

Gateway complexo prematuro pode gerar:

custo;
lock-in;
latência;
dependência operacional.

38. Webhooks, filas, eventos e integrações

38.1 Polling

Cliente pergunta repetidamente:

A ordem terminou?
A ordem terminou?

38.2 Webhook

Servidor notifica:

POST https://cliente.com/webhooks/ordem-concluida

38.3 Segurança de webhook

HTTPS;
assinatura HMAC;
timestamp;
prevenção de replay;
allowlist opcional;
idempotência;
retry;
fila;
dead-letter;
logs.

38.4 Assinatura conceitual

assinatura = HMAC(segredo, timestamp + "." + corpo_bruto)

O consumidor recalcula e compara em tempo constante.

38.5 Filas e brokers

Exemplos:

RabbitMQ;
Apache Kafka;
NATS;
Amazon SQS;
Google Pub/Sub;
Azure Service Bus.

38.6 Entrega

Pode ser:

at-most-once;
at-least-once;
effectively-once com controles;
ordering parcial ou total.

38.7 Idempotência do consumidor

Mensagens podem ser repetidas. O consumidor deve evitar duplicar efeito.

38.8 Dead-letter queue

Armazena mensagens que não foram processadas após tentativas.

38.9 ETL/ELT

Adequado para dados analíticos e lotes, não necessariamente transação online.

38.10 Arquivos

CSV/XML/SFTP ainda são válidos quando:

fornecedor não possui API;
integração é diária;
volume é grande;
latência não é crítica.

39. ERP, Supabase e bancos de dados

39.1 ERP

Sistema de gestão empresarial.

Possui:

módulos;
processos;
regras;
usuários;
banco;
integrações;
relatórios.

Exemplos de domínio:

compras;
estoque;
financeiro;
manutenção;
fiscal;
ativos.

39.2 Supabase

Plataforma de backend que inclui, entre outros recursos:

PostgreSQL;
autenticação;
storage;
APIs;
funções;
realtime.

Não é apenas banco.

39.3 Banco relacional

Organiza dados em tabelas e relações.

39.4 NoSQL

Família de bancos com modelos diferentes:

documento;
chave-valor;
coluna;
grafo.

39.5 API sobre banco

Não exponha tabela automaticamente sem analisar:

autorização;
regra de negócio;
validação;
histórico;
performance;
dados sensíveis.

39.6 Row Level Security

Pode restringir linhas no banco. É útil, mas precisa de política bem projetada e testes.

39.7 Fonte da verdade

Em integração, defina:

qual sistema é mestre;
quem pode alterar;
como conflitos são resolvidos;
qual latência é aceitável;
como reconciliar dados.

40. APIs de inteligência artificial

40.1 Arquitetura recomendada

Frontend
  ↓
Seu backend
  ↓
API do provedor de IA

Não coloque chave secreta do provedor diretamente no navegador ou app mobile.

40.2 Conceitos específicos

modelo;
prompt;
mensagem;
contexto;
token de entrada;
token de saída;
janela de contexto;
streaming;
tool/function calling;
embedding;
vector store;
RAG;
fine-tuning;
evals;
rate limits;
custo.

40.3 Tokens de linguagem

São unidades de processamento de texto. A quantidade depende do tokenizer e do modelo.

40.4 Custo

Pode depender de:

tokens de entrada;
tokens de saída;
imagem;
áudio;
armazenamento;
busca;
ferramentas;
cache;
lote;
serviço.

40.5 Segurança

chave no backend;
projeto separado por ambiente;
limites de gasto;
rate limit por usuário;
moderação conforme uso;
logs com privacidade;
não enviar dado desnecessário;
proteção contra prompt injection;
autorização das ferramentas;
validação da saída;
evals;
modelos versionados quando disponível.

40.6 Sites oficiais de desenvolvedores de IA

OpenAI

documentação da plataforma;
referência da API;
Cookbook;
guias de produção;
segurança de chaves;
Responses API.

Anthropic

Claude Platform Docs;
Messages API;
SDKs;
rate limits;
ferramentas.

Google

Google AI for Developers;
Gemini API;
referências REST e SDK;
AI Studio.

Microsoft

Microsoft Foundry;
Azure OpenAI;
Azure API Management;
identidade e rede Azure.

AWS

Amazon Bedrock;
IAM;
API Gateway;
CloudWatch.

40.7 Prática importante

Não use exemplos antigos sem verificar depreciação. APIs de IA mudam rapidamente.

Na documentação oficial da OpenAI consultada em 2026, a Assistants API aparece como legada/depreciada em favor da Responses API. A Microsoft também publicou cronograma de aposentadoria de sua experiência clássica correspondente. Sempre confirmar antes de iniciar projeto.

40.8 Evals

Uma aplicação de IA deve medir:

precisão;
aderência;
segurança;
custo;
latência;
regressão;
falhas por classe;
desempenho com casos reais.

41. Exemplo completo: aplicativo de manutenção

41.1 Objetivo

Permitir que eletricistas consultem e concluam ordens.

41.2 Perfis

eletricista: consultar e concluir
supervisor: criar, atribuir e aprovar
administrador: configurar

41.3 Endpoints

GET    /v1/ordens-servico
GET    /v1/ordens-servico/{id}
POST   /v1/ordens-servico
PATCH  /v1/ordens-servico/{id}
POST   /v1/ordens-servico/{id}/concluir
GET    /v1/equipamentos

41.4 Login corporativo

Aplicativo → OIDC/Entra ID → token → API

41.5 Consulta

GET /v1/ordens-servico?status=aberta&limit=50
Authorization: Bearer ACCESS_TOKEN

41.6 Backend valida

assinatura;
issuer;
audience;
expiração;
usuário ativo;
escopo;
unidade;
acesso ao objeto.

41.7 Conclusão

POST /v1/ordens-servico/101/concluir
Authorization: Bearer ACCESS_TOKEN
Idempotency-Key: 550e...
Content-Type: application/json

{
  "observacao": "Aperto realizado e temperatura normalizada.",
  "concluidaEm": "2026-08-01T23:30:00-03:00"
}

41.8 Regra

somente responsável ou supervisor;
ordem precisa estar aberta;
observação obrigatória;
anexos verificados;
histórico imutável.

41.9 Resposta

200 OK

{
  "id": 101,
  "status": "concluida",
  "concluidaPor": "usuario-123",
  "concluidaEm": "2026-08-01T23:30:00-03:00"
}

41.10 Auditoria

{
  "evento": "ordem.concluida",
  "ordemId": 101,
  "atorId": "usuario-123",
  "timestamp": "2026-08-01T23:30:00-03:00",
  "requestId": "6bf21"
}

41.11 Integração com ERP

Após concluir:

publicar evento;
consumidor integra com ERP;
retry em falha;
idempotência;
status de sincronização;
reconciliação.

Não bloquear o eletricista indefinidamente por uma indisponibilidade temporária do ERP, salvo se a regra exigir transação síncrona.

42. Como solicitar uma API

42.1 Modelo de solicitação

Objetivo

Disponibilizar integração para consulta e atualização de ordens de serviço.

Consumidores

aplicativo web;
aplicativo mobile;
Power BI;
ERP;
fornecedor.

Operações

listar;
consultar;
criar;
atribuir;
concluir;
cancelar;
anexar.

Dados

Definir schema de cada operação.

Regras

permissões;
estados;
campos obrigatórios;
transições;
histórico;
duplicidade.

Autenticação

SSO;
OAuth/OIDC;
client credentials;
API key;
certificado.

Volumetria

registros;
chamadas;
simultaneidade;
crescimento;
anexos.

Requisitos não funcionais

disponibilidade;
latência;
retenção;
segurança;
auditoria;
LGPD;
recuperação.

Entregáveis

OpenAPI;
coleção de testes;
sandbox;
credenciais;
exemplos;
changelog;
runbook;
monitoramento;
critérios de aceite.

43. Perguntas que os desenvolvedores farão

Negócio

Qual problema será resolvido?
Qual é a fonte da verdade?
Quem pode fazer cada ação?
Quais exceções existem?
O que é irreversível?

Dados

Quais campos?
Quais tipos?
Quais obrigatórios?
Há dados pessoais?
Há arquivos?
Qual histórico?

Integração

O sistema possui API?
Existe documentação?
Existe sandbox?
Qual autenticação?
Existe webhook?
Há VPN?
Quais IPs?
Quem libera?

Volume

Quantos usuários?
Quantos registros?
Quantas chamadas por minuto?
Qual tamanho de payload?
Precisa de tempo real?

Operação

Qual SLA?
Quem dá suporte?
Como monitorar?
Como reconciliar?
Como fazer rollback?
Qual janela de manutenção?

Segurança

SSO?
MFA?
perfis?
segregação?
retenção?
auditoria?
teste de segurança?
gestão de segredos?

44. Status de implementação

Descoberta

Requisitos e sistemas sendo levantados.

Refinamento

Regras e critérios sendo detalhados.

Design

Contrato e arquitetura sendo elaborados.

Aguardando dependência

Exemplos:

credencial;
documentação;
acesso;
regra;
fornecedor;
firewall.

Em desenvolvimento

Código em execução.

Em revisão

Code review, arquitetura ou segurança.

Em testes

Testes funcionais, contrato, carga ou segurança.

Sandbox disponível

Ambiente de teste liberado.

Em homologação

Usuários validando.

Homologado

Aprovado.

Agendado para produção

Mudança aprovada e planejada.

Em produção

Disponível.

Monitoramento assistido

Período inicial de observação.

Bloqueado

Impedimento concreto com responsável e ação necessária.

Reprovado

Critério não atendido.

Rollback executado

Versão revertida.

Débito técnico registrado

Limitação aceita formalmente, com risco, responsável e prazo.

45. Critérios de aceite

Funcional

endpoints executam regras;
erros corretos;
filtros funcionam;
paginação funciona;
estados válidos;
histórico gerado.

Contrato

OpenAPI válida;
exemplos;
schemas;
erros;
versão;
changelog.

Segurança

HTTPS;
autenticação;
autorização por função e objeto;
segredos protegidos;
tokens validados;
rate limit;
logs sem segredo;
testes OWASP relevantes.

Performance

p95 definido;
carga testada;
payload limitado;
consultas revisadas;
timeout configurado.

Resiliência

retries controlados;
idempotência;
dependência indisponível testada;
fila e DLQ quando aplicável;
backup/restauração.

Operação

dashboards;
alertas;
request ID;
runbook;
ownership;
suporte;
rollback.

Privacidade

minimização;
finalidade;
retenção;
acesso;
exclusão quando aplicável;
base legal validada pela área competente.

46. Roteiro de estudos

Etapa 1 — Fundamentos

cliente e servidor;
URL;
DNS;
HTTP;
JSON;
métodos;
status.

Prática

Usar cURL ou Bruno em API pública de teste.

Etapa 2 — Contrato

OpenAPI;
JSON Schema;
parâmetros;
paginação;
erros.

Prática

Escrever OpenAPI de ordens de serviço.

Etapa 3 — Backend mínimo

rota;
validação;
serviço;
repositório;
banco;
testes.

Prática

Criar API local com FastAPI, ASP.NET Core ou Spring Boot.

Etapa 4 — Segurança

autenticação;
autorização;
sessão;
JWT;
OAuth/OIDC;
OWASP.

Prática

Criar matriz de permissões e testes negativos.

Etapa 5 — Integração

webhook;
fila;
retry;
idempotência;
ERP.

Etapa 6 — Produção

containers;
CI/CD;
logs;
métricas;
traces;
gateway;
backup;
runbook.

Etapa 7 — IA

API de modelo;
tokens;
streaming;
tools;
RAG;
evals;
segurança de agente.

47. Personalidades e autores de referência

Esta não é uma lista de “autoridades infalíveis”. São pessoas com contribuições relevantes para estudo.

Roy Fielding

descreveu REST em sua dissertação;
coautor de especificações HTTP;
referência para arquitetura web.

Tim Berners-Lee

criador da World Wide Web;
fundamentos de URLs, HTTP e web.

Douglas Crockford

popularização e especificação histórica do JSON;
conhecido por trabalhos em JavaScript.

Martin Fowler

arquitetura de software;
refatoração;
integração;
microsserviços;
design de sistemas.

Sam Newman

microsserviços;
evolução arquitetural;
sistemas distribuídos.

Aaron Parecki

OAuth;
identidade;
editor e participante de padrões;
mantenedor de oauth.net.

Daniel Stenberg

criador e mantenedor do curl;
HTTP e transferência de dados.

Kin Lane

API Evangelist;
tecnologia, governança, negócios e política de APIs.

Erik Wilde

arquitetura e design de APIs;
coautor da RFC 9457.

Arnaud Lauret

API design;
autor conhecido como API Handyman.

Mike Amundsen

APIs, hipermídia e sistemas distribuídos.

Troy Hunt

segurança de aplicações;
identidade;
vazamentos;
boas práticas práticas.

Bruce Schneier

engenharia de segurança e análise de risco.

Observação

Aprenda conceitos nas especificações e valide opiniões com contexto. Personalidade influente não substitui requisito, teste ou evidência.

48. Fóruns e comunidades

48.1 Stack Overflow

Útil para:

erros específicos;
exemplos;
compatibilidade;
problemas de biblioteca.

Cuidados:

resposta pode estar desatualizada;
versão pode ser diferente;
votos não garantem segurança;
confirme na documentação oficial.

48.2 GitHub

issues;
discussions;
releases;
advisories;
exemplos;
código-fonte.

Prefira repositório oficial.

48.3 Reddit

Comunidades como:

r/webdev;
r/programming;
r/backend;
r/FastAPI;
r/dotnet;
r/java;
r/golang;
r/cybersecurity.

Use como experiência complementar, não como fonte normativa.

48.4 Comunidades oficiais

Postman Community/Discord;
OWASP chapters e projetos;
OpenAPI Initiative;
AsyncAPI community;
fóruns dos frameworks;
IETF mailing lists;
OAuth Working Group.

48.5 Regra de confiança

Ordem preferida:

especificação;
documentação oficial;
código e testes;
release notes;
issue oficial;
artigo de especialista;
fórum;
vídeo ou postagem sem fonte.

49. Documentos e sites oficiais

49.1 Protocolos e padrões

HTTP Semantics — RFC 9110
https://www.rfc-editor.org/rfc/rfc9110.html
HTTP Caching — RFC 9111
https://www.rfc-editor.org/rfc/rfc9111.html
JSON — RFC 8259
https://www.rfc-editor.org/rfc/rfc8259.html
OAuth 2.0 — RFC 6749
https://www.rfc-editor.org/rfc/rfc6749.html
OAuth 2.0 Security Best Current Practice — RFC 9700
https://www.rfc-editor.org/rfc/rfc9700.html
OAuth 2.1 — Internet-Draft
https://datatracker.ietf.org/doc/draft-ietf-oauth-v2-1/
OpenID Connect Core
https://openid.net/specs/openid-connect-core-1_0-final.html
Problem Details — RFC 9457
https://www.rfc-editor.org/rfc/rfc9457.html

49.2 Especificações de API

OpenAPI
https://spec.openapis.org/oas/
Arazzo
https://spec.openapis.org/arazzo/latest.html
AsyncAPI
https://www.asyncapi.com/docs/reference/specification/latest
JSON Schema
https://json-schema.org/
GraphQL
https://graphql.org/learn/
gRPC
https://grpc.io/docs/

49.3 Diretrizes de design

Microsoft REST API Guidelines
https://github.com/microsoft/api-guidelines
Google API Design Guide
https://cloud.google.com/apis/design
Google API Improvement Proposals
https://google.aip.dev/
Zalando RESTful API and Event Guidelines
https://opensource.zalando.com/restful-api-guidelines/
Azure API Design Best Practices
https://learn.microsoft.com/azure/architecture/best-practices/api-design

49.4 Segurança

OWASP API Security
https://owasp.org/API-Security/
OWASP API Security Top 10 — 2023
https://owasp.org/API-Security/editions/2023/en/0x11-t10/
OWASP Top 10 — 2025
https://owasp.org/Top10/2025/
OWASP ASVS
https://owasp.org/www-project-application-security-verification-standard/
OWASP Cheat Sheet Series
https://cheatsheetseries.owasp.org/
NIST Digital Identity Guidelines 800-63-4
https://pages.nist.gov/800-63-4/
NIST SSDF
https://csrc.nist.gov/projects/ssdf
CISA Secure by Design
https://www.cisa.gov/securebydesign

49.5 Ferramentas

cURL
https://curl.se/docs/
Postman
https://learning.postman.com/
Bruno
https://docs.usebruno.com/
FastAPI
https://fastapi.tiangolo.com/
Spring
https://spring.io/guides/gs/rest-service/
ASP.NET Core Web API
https://learn.microsoft.com/aspnet/core/web-api/
Express
https://expressjs.com/

49.6 IA

OpenAI Platform
https://platform.openai.com/docs/
OpenAI API Reference
https://platform.openai.com/docs/api-reference/
OpenAI Cookbook
https://cookbook.openai.com/
Anthropic Docs
https://docs.anthropic.com/
Google AI for Developers
https://ai.google.dev/
Microsoft Foundry / Azure OpenAI
https://learn.microsoft.com/azure/ai-foundry/
Amazon Bedrock
https://docs.aws.amazon.com/bedrock/
NIST AI RMF
https://www.nist.gov/itl/ai-risk-management-framework
OWASP GenAI Security Project
https://genai.owasp.org/

49.7 Estudos citados e úteis

Fielding, Roy. Architectural Styles and the Design of Network-based Software Architectures
https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
Estudos empíricos sobre regras de design REST e compreensibilidade podem ser encontrados nas publicações de Justus Bogner, Sebastian Kotstein e colaboradores.
Pesquisa sobre evolução de APIs em microsserviços destaca compatibilidade retroativa, comunicação de mudanças e dependência de consumidores como desafios recorrentes.

50. Glossário

API

Contrato de comunicação entre softwares.

API Gateway

Componente que aplica políticas e roteia chamadas.

API Key

Chave que identifica aplicação ou projeto.

Authentication

Processo de verificar identidade.

Authorization

Processo de permitir ou negar ação.

Backend

Camada de lógica e dados.

Bearer token

Token apresentado por quem o possui.

Body

Corpo da mensagem.

Cache

Reutilização de resposta armazenada.

Claim

Declaração contida em token.

Client

Software que faz requisição.

CORS

Política de navegador para requisições entre origens.

CRUD

Create, Read, Update, Delete.

DTO

Objeto de transferência de dados.

Endpoint

Combinação de método e endereço exposta pela API.

ERP

Sistema integrado de gestão empresarial.

Frontend

Interface do usuário.

Hash

Transformação unidirecional.

Header

Metadado HTTP.

HTTP

Protocolo de aplicação da web.

HTTPS

HTTP protegido por TLS.

Idempotência

Repetir operação produz estado final equivalente.

IdP

Provedor de identidade.

JSON

Formato textual para dados estruturados.

JWT

Formato de token com claims e assinatura.

Latência

Tempo da operação.

OAuth

Framework de autorização delegada.

OIDC

Camada de identidade sobre OAuth 2.0.

OpenAPI

Especificação para descrever APIs HTTP.

Payload

Dados transportados.

Query parameter

Parâmetro após ? na URL.

Rate limit

Limite de velocidade de uso.

REST

Estilo arquitetural.

Retry

Nova tentativa após falha.

RPC

Chamada de procedimento remoto.

Schema

Definição da estrutura dos dados.

Scope

Permissão delegada.

Server

Software que responde.

SLO

Objetivo interno de nível de serviço.

SSO

Status code

Código de resultado HTTP.

Supabase

Plataforma de backend baseada em PostgreSQL e serviços associados.

TLS

Protocolo criptográfico usado no HTTPS.

Token de IA

Unidade de processamento de linguagem; não confundir com credencial.

Trace

Rastreamento de uma operação distribuída.

URL

Endereço de recurso.

Webhook

Notificação HTTP iniciada pelo sistema que detectou um evento.

Conclusão executiva

Uma API profissional não é apenas um endpoint que “funciona no Postman”.

Ela precisa combinar:

contrato claro;
regras corretas;
autenticação;
autorização;
validação;
segurança;
compatibilidade;
desempenho;
testes;
documentação;
observabilidade;
operação;
ownership;
evolução controlada.

A sequência correta é:

Problema de negócio
        ↓
Contrato
        ↓
Arquitetura
        ↓
Segurança
        ↓
Implementação
        ↓
Testes
        ↓
Homologação
        ↓
Produção
        ↓
Monitoramento e evolução

A recomendação principal é dominar primeiro HTTP, JSON, contratos, autenticação e autorização. Depois, avançar para banco de dados, arquitetura distribuída, segurança e APIs de IA.

Registro das principais fontes verificadas

Este manual foi consolidado com base em especificações e páginas oficiais consultadas até 1º de agosto de 2026, incluindo:

RFC Editor/IETF;
OpenAPI Initiative;
OpenID Foundation;
OWASP;
NIST;
CISA;
Microsoft;
Google;
Postman;
cURL;
AsyncAPI;
JSON Schema;
GraphQL;
gRPC;
OpenAI;
Anthropic;
Google AI for Developers.

As fontes comunitárias foram tratadas apenas como complemento, não como norma.