Tempo de leitura estimado : 8 min · Publicado
Escolha as tarefas antes dos endereços
A lista usa, como encontrar um produto, disponibilidade de leitura, atualização de um registro ou processamento de rastreamento. Defina pessoas e sistemas autorizados para cada operação. Uma API de leitura pública e uma API administrativa têm requisitos de acesso diferentes.
Prepare um exemplo de solicitação e resposta para cada tarefa essencial usando valores sintéticos e campos explicados. Distinguir identificadores estáveis, etiquetas, unidades e datas. Defina dados ausentes em vez de substituir valores plausíveis por informações desconhecidas.
Defina identificadores grandes no contrato JSON. Com Number binary64 de JavaScript, inteiros de −9007199254740991 a 9007199254740991 estão no intervalo exato de interoperabilidade RFC 8259. 9007199254740992 é representável mas não seguro: o token vizinho 9007199254740993 passa a 9007199254740992 na descodificação JSON JavaScript padrão.
Como cadeia JSON, o identificador conserva os algarismos. Acorde o tipo entre produtor, esquema e consumidor; converter em texto um Number arredondado não recupera o original. Outras bibliotecas podem preservar mais precisão: teste clientes suportados. JSON válido não garante fidelidade e o tipo não deve mudar silenciosamente.
Desloque a tabela horizontalmente para ler todas as colunas. Com o teclado, coloque o foco na tabela e utilize as teclas de seta.
| Token JSON de exemplo | Valor JavaScript apresentado | Interpretação |
|---|---|---|
| 9007199254740991 | 9007199254740991 | Inteiro seguro no exemplo |
| 9007199254740992 | 9007199254740992 | Exato, mas fora do intervalo seguro |
| 9007199254740993 | 9007199254740992 | Arredondado: último algarismo original perdido |
| "9007199254740993" | "9007199254740993" | Cadeia exata; tipo textual acordado |
Descreva um contrato explícito
O OpenAPI fornece um formato de descrição independente do idioma para APIs HTTP, cobrindo operações, parâmetros, respostas e modelos. Escolha uma versão suportada por suas ferramentas e mantenha o documento com o projeto; A versão mais recente não é automaticamente adequada para todas as cadeias de ferramentas.
Limites de uso de documentos, paginação, filtros, pedidos, erros e respostas vazias. Não trate os COs como prova de autorização. Revise a operação e os controles de acesso em nível de objeto com a equipe técnica.
Para uma API fictícia de tratamento de pedidos, descreva separadamente as quatro respostas abaixo. Neste contrato, 201 devolve um recurso criado com o cabeçalho Location; 202 fornece uma referência de acompanhamento porque o trabalho não terminou. Não transforme qualquer resposta 2xx em «operação concluída». O cliente deve ler o estado, os cabeçalhos e o modelo previsto para a operação.
Uma resposta 204 não tem corpo para descodificar como JSON. Neste exemplo, uma instrução de sintaxe correta que viola uma regra de negócio recebe 422 com um problema estruturado em application/problem+json. Se existir o membro status, o gerador deve fazê-lo corresponder ao estado HTTP real; o texto traduzido de detail não deve ser a chave de decisão do programa. Documente identificadores estáveis do problema e a correção esperada.
Desloque a tabela horizontalmente para ler todas as colunas. Com o teclado, coloque o foco na tabela e utilize as teclas de seta.
| Resposta prevista | Facto comprovado | Verificação do consumidor |
|---|---|---|
| 201 Created | Recurso criado | Verificar Location exigido pelo contrato e identificador criado |
| 202 Accepted | Tratamento aceite, não concluído | Guardar a referência; aguardar o resultado final |
| 204 No Content | Ação bem-sucedida sem corpo de resposta | Não descodificar um corpo vazio como JSON |
| 422 Unprocessable Content | Instrução compreendida mas não processável segundo a regra | Ler o problema estruturado e propor uma correção adequada |
- RFC 9110 : HTTP Semantics
RFC 9110, consultada em 22 de outubro de 2026: semântica dos estados. As respostas e campos obrigatórios definem um contrato fictício.
- RFC 9457 : Problem Details
RFC 9457, consultada em 22 de outubro de 2026: formato dos problemas e função do membro status.
Impedir que uma alteração substitua a de outro editor
- Duas leituras de r7
- Primeira escrita: r8
- Escrita antiga: 412
- Comparar antes de retomar
Caso fictício: dois editores abrem DEMO-17 com o ETag forte "r7". O primeiro guarda uma correção; a representação atual passa a "r8". O segundo continua a trabalhar sobre "r7". Uma escrita condicional permite detetar a diferença antes de substituir a versão publicada.
Numa API que suporte este contrato, o cliente envia If-Match com o validador forte recebido. O servidor compara a versão antes de escrever: o exemplo prevê 412 se mudou. W/"r7" é fraco e não satisfaz a comparação forte. If-Match: * verifica a existência de uma representação atual, não que tenha ficado inalterada desde a leitura.
Conserve o rascunho do segundo editor, leia a versão atual e apresente as diferenças antes de decidir um novo envio. Trocar automaticamente o validador por "r8" e reenviar o rascunho antigo contornaria a proteção. Verificação e escrita devem ser indivisíveis no armazenamento; dois pedidos concorrentes com o mesmo validador não devem ambos substituir a mesma versão.
Este controlo não substitui autenticação, permissões sobre a ficha ou validação dos campos. Também não garante a execução única de uma chamada externa. Teste essas propriedades separadamente e documente precondições em falta; 428 pode exigir um pedido condicional.
Desloque a tabela horizontalmente para ler todas as colunas. Com o teclado, coloque o foco na tabela e utilize as teclas de seta.
| Etapa | Versão e pedido | Resultado previsto neste contrato |
|---|---|---|
| Leitura dos dois editores | ETag: "r7" | Cada um conserva o validador com o rascunho. |
| Primeira gravação | If-Match: "r7" → versão "r8" | A primeira correção é conservada. |
| Segunda gravação desatualizada | If-Match: "r7"; versão atual "r8" | 412; não substituir a correção guardada. |
| Conciliação explícita | Ler "r8", comparar e decidir | Conservar o rascunho e verificar permissões antes de nova escrita. |
- IETF · RFC 9110 § 13.1.1
IETF : Escritas condicionais e precondições
- IETF · RFC 6585 § 3
428 · Precondition Required
Teste limites e permissões
Tente um objeto existente, um objeto ausente, um parâmetro inválido e uma lista com mais de uma página. Verifique a próxima página quanto a perdas ou repetições no modelo de atualização escolhido. Limitações de estado que a API não pode garantir.
Use contas de teste com permissões diferentes. A tentativa de leituras e alterações fora do escopo permitido usando dados sintéticos. Registre os status esperados e as mensagens úteis sem expor traços internos ou segredos de configuração.
Planeje a mudança e o suporte
Distinguir um campo adicionado de um campo removido ou um significado alterado. Identifique os consumidores antes de uma mudança incompatível. Explique o período de transição e como detectar integrações ainda usando o contrato anterior.
Forneça um exemplo executável para um ambiente de teste, uma matriz de teste e um contato técnico. Relacione os erros observados a exemplos documentados após o lançamento. A documentação limitada ao caso ideal deixa os integradores sem orientação para recusas e interrupções.
Documentação principal: Iniciativa OpenAPI : Especificação.
Documentos de referência
- Iniciativa OpenAPI : Especificação · Fonte consultada
- IETF : RFC 8259: JSON numbers · Fonte consultada
- TC39 : Number.isSafeInteger · Fonte consultada
Conteúdo atualizado
Referências documentadas para este tema
| Referência | Valor ou sintaxe | Âmbito |
|---|---|---|
| RFC 8259 · JSON | application/json · UTF-8 | JSON padrão não admite comentários nem vírgulas finais; as cadeias usam aspas duplas. |
| RFC 3339 · Date-time | 2026-10-22T09:00:00+02:00 | O desvio explícito relaciona a hora local com UTC; este exemplo não é uma marcação. |
| HTTP · If-Match | If-Match: "r7" → 412 | If-Match compara um validador forte antes de escrever. No contrato ilustrado, uma versão antiga recebe 412; conserve o rascunho para comparar alterações. |
| HTTP · 428 | 428 · Precondition Required | 428 permite exigir um pedido condicional. Documente a utilização no contrato; o estado não fornece, por si só, um bloqueio. |
As datas indicam a consulta das fontes. Estes dados não constituem uma auditoria do site nem uma declaração global de conformidade.
