APRENDER. PRATICAR. EVOLUIR.Conceito e mecanismo
Uma API permite que aplicações cooperem através de um contrato observável. O consumidor precisa de conhecer recursos, operações, dados obrigatórios, resultados e limites. REST descreve um estilo arquitetural com restrições de interação; devolver JSON por HTTP não demonstra, por si só, todas essas propriedades. O estado de negócio pode persistir, enquanto cada pedido transporta contexto suficiente para ser interpretado sem depender de uma conversa implícita guardada entre pedidos. Separa a representação pública da organização interna da base de dados. Essa separação permite adaptar implementação sem obrigar todos os consumidores a conhecer tabelas, filas ou nomes internos.
Aplicação guiada
Num cenário fictício de fundos, uma API expõe pedidos de reconciliação e respetivo estado. O contrato deve definir identificador, moeda, precisão, estados possíveis e erros. OpenAPI ajuda a descrever operações e schemas de forma processável; a versão do documento OpenAPI não é a versão comercial da API. Um componente declarado mas nunca referenciado não entra automaticamente numa operação. A documentação também não comprova que a implementação valida o payload ou aplica autorização. Durante uma alteração, compara consumidores reais com o contrato: converter um montante de número para texto pode exigir adaptação, mesmo que o significado comercial pareça igual. Mantém exemplos fictícios, sem credenciais ou dados de clientes.
Um schema novo só protege a integração se estiver ligado à operação e for aplicado pelos controlos previstos.
Armadilhas comuns
JSON como prova de REST; schema como enforcement; versão OpenAPI como versão do produto.
Tópicos relacionados: Pedidos e resultados · Concorrência e repetição · Autorização e fronteiras
Torna explícito o contrato que os consumidores realmente usam.
Referência: OpenAPI Specification3.2.1 · HTTP semantics RFC9110; OpenAPI3.2.1; selected primary standards and provider contracts consulted2026-09-30