Pesquisar
Introduza pelo menos dois caracteres, sem dados pessoais.

    BibliotecaArtigos e FAQs Seu projetoSolicite um orçamento
    LínguaPT ▾
    Guias práticos

    Documente e teste uma API de seus casos de uso

    Uma API útil permite que outra equipe entenda o que pode solicitar e o que receberá. Seu contrato deve ser testável, versionado e consistente com o serviço operacional.

    Veja o método

    Ilustração — Documente e teste uma API de seus casos de uso
    Ilustração gerada por IA

    Escolha as tarefas antes dos endereços

    JavaScript: 9007199254740993 numérico arredonda; a cadeia conserva algarismos.
    Ilustração · Exemplo JSON.parse: Number arredonda, String conserva algarismos. Acordar representação antes de converter.

    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.

    Descodificação JSON JavaScript: precisão e tipo
    Token JSON de exemploValor JavaScript apresentadoInterpretação
    90071992547409919007199254740991Inteiro seguro no exemplo
    90071992547409929007199254740992Exato, mas fora do intervalo seguro
    90071992547409939007199254740992Arredondado: ú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.

    Quatro respostas de uma API fictícia e as consequências no cliente
    Resposta previstaFacto comprovadoVerificação do consumidor
    201 CreatedRecurso criadoVerificar Location exigido pelo contrato e identificador criado
    202 AcceptedTratamento aceite, não concluídoGuardar a referência; aguardar o resultado final
    204 No ContentAção bem-sucedida sem corpo de respostaNão descodificar um corpo vazio como JSON
    422 Unprocessable ContentInstrução compreendida mas não processável segundo a regraLer 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

    1. Duas leituras de r7
    2. Primeira escrita: r8
    3. Escrita antiga: 412
    4. 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.

    Dois editores, uma versão atual: sequência fictícia de teste
    EtapaVersão e pedidoResultado previsto neste contrato
    Leitura dos dois editoresETag: "r7"Cada um conserva o validador com o rascunho.
    Primeira gravaçãoIf-Match: "r7" → versão "r8"A primeira correção é conservada.
    Segunda gravação desatualizadaIf-Match: "r7"; versão atual "r8"412; não substituir a correção guardada.
    Conciliação explícitaLer "r8", comparar e decidirConservar o rascunho e verificar permissões antes de nova escrita.

    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

    Conteúdo atualizado

    Referências documentadas para este tema

    Referências documentadas para este tema
    ReferênciaValor ou sintaxeÂmbito
    RFC 8259 · JSON
    application/json · UTF-8JSON 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:00O desvio explícito relaciona a hora local com UTC; este exemplo não é uma marcação.
    HTTP · If-Match
    If-Match: "r7" → 412If-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 Required428 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.

    Distinguir estado HTTP, JSON e resultado de negócio

    Escolha uma troca fictícia e experimente a leitura local. Sucesso HTTP, JSON legível e operação concluída exigem verificações separadas.

    Os excertos são incompletos e usam endereços de demonstração. O ensaio cria uma Response em memória: não contacta servidores nem simula rede, cache ou processamento de negócio.

    200Uma nova representação completa
    Significado
    Neste excerto, o servidor responde ao GET condicional com corpo JSON e validador demo-v2.
    O que verificar
    Compare If-None-Match, ETag e a revisão no corpo. O ensaio local analisa o JSON deste exemplo.
    Atenção
    Um 200 não garante JSON válido nem dados de negócio corretos. A análise bem-sucedida não valida o esquema dos seus dados.
    Excerto de troca fictícia
    GET /demo/catalogue
    If-None-Match: "demo-v1"
    
    HTTP/1.1 200 OK
    ETag: "demo-v2"
    Content-Type: application/json
    
    {"revision":"demo-v2"}

    202Aceite, processamento ainda pendente
    Significado
    202 indica aceitação para processamento, não conclusão. O corpo fictício indica queued.
    O que verificar
    Guarde DEMO-42 e acompanhe o estado segundo o contrato da API, com permissões e limites de repetição.
    Atenção
    Response.ok é true. Nem esse valor nem JSON legível provam a conclusão. Campos e endereço de acompanhamento são convenções fictícias.
    Excerto de troca fictícia
    POST /demo/jobs
    
    HTTP/1.1 202 Accepted
    Location: /demo/jobs/DEMO-42
    Content-Type: application/json
    
    {"job":"DEMO-42","status":"queued"}

    204Pedido satisfeito, sem corpo
    Significado
    204 indica que o servidor satisfez o pedido sem conteúdo de resposta. O excerto não transmite JSON.
    O que verificar
    Trate o corpo ausente segundo o contrato. Confirme o que o destinatário valida antes de comunicar um resultado ao visitante.
    Atenção
    Analisar o corpo vazio como JSON falha apesar de Response.ok ser true. Num webhook pode estar confirmada apenas a receção; as ações seguintes exigem reconciliação.
    Excerto de troca fictícia
    POST /demo/events
    
    HTTP/1.1 204 No Content

    304Cópia revalidada, sem novo corpo
    Significado
    304 responde a um pedido condicional: a representação guardada pode ser reutilizada. Não fornece um novo corpo.
    O que verificar
    Compare o validador enviado com a cópia demo-v2 disponível. A interpretação depende também dessa cópia.
    Atenção
    O ensaio cria uma Response 304 isolada, não uma cache HTTP. Num fetch real o navegador pode fornecer a resposta guardada: estado de rede e estado exposto ao script podem diferir.
    Excerto de troca fictícia
    GET /demo/catalogue
    If-None-Match: "demo-v2"
    
    HTTP/1.1 304 Not Modified
    ETag: "demo-v2"

    Referências técnicas : RFC 9110 §15 · MDN · Response.ok · MDN · Response.json() · WHATWG · Fetch · .

    Matriz de validação funcional para se adaptar ao projeto

    Esses controles propostos usam casos fictícios. Decida qual comportamento é esperado com a equipe, anote o resultado e atribua discrepâncias não resolvidas antes da publicação.

    Desloque a tabela horizontalmente para ler todas as colunas. Com o teclado, coloque o foco na tabela e utilize as teclas de seta.

    Casos de teste, resultados esperados e evidências úteis
    CasoResultado esperadoProva para guardar
    Recursos presentes e ausentesCada resultado corresponde ao status documentado e ao modelo de resposta.Solicitação, resposta e exemplo de contrato correspondente capturado no ambiente de teste.
    Parâmetro fora da faixaA recusa é compreensível e não expõe nenhum rastreamento interno da pilha.Mensagem pública e resultado retidos na Matriz de Aceitação.
    Dois níveis de permissãoUm recurso proibido permanece inacessível mesmo com um identificador conhecido.Comparou os resultados usando duas contas sintéticas com permissões explicitamente diferentes.
    Paginação e filtro alteradoO tratamento de tokens e o comportamento de reinicialização da jornada são definidos.ordenação, identificadores retornados e regras aplicadas quando o filtro muda.

    Perguntas frequentes

    A documentação gerada é suficiente para testar uma API?

    Ele ajuda a ler um contrato, mas as permissões, dados ausentes, erros, listas e alterações exigem testes. Compare exemplos com as respostas reais do ambiente de teste.

    Os COs substituem as permissões de acesso?

    Não. As regras de origem cruzada não substituem a operação do serviço e as permissões de objeto. Descreva essas permissões e teste a aplicação do lado do servidor com contas de teste.