Testando endpoints com o Try It!

Try It! é o console API do Document360, incorporado diretamente na sua referência de API publicada. Ele permite que desenvolvedores enviem requisições reais para seus endpoints da API e vejam respostas ao vivo sem sair da documentação ou escrever código.

Este artigo explica como o console Try It! funciona na sua referência de API publicada — como abri-lo, construir e enviar uma solicitação, ler a resposta e o que o console suporta ou não. Para detalhes sobre como configurar cada método de autenticação, veja Autorizar requisições no console Try It.

O que tentar!

A partir de qualquer página de endpoint na sua referência de API publicada, os desenvolvedores podem:

• Abra um console interativo inline no endpoint, sem sair da página
• Preencha os parâmetros do caminho e da consulta, cabeçalhos e (para métodos de escrita) o corpo da requisição
• Forneça credenciais de autenticação para o esquema de segurança do endpoint
• Envie uma solicitação ao vivo e veja a resposta real — status, momento, cabeçalhos e corpo

Abrindo o console Try It

Em qualquer página de endpoint, o método e a URL do endpoint aparecem no topo, com um botão Tente ao lado.

1. Clique em tentar. O console interativo abre em linha, diretamente abaixo da URL do endpoint.
2. Construa sua solicitação usando as abas descritas abaixo e clique em Enviar.
3. Quando terminar, clique no ícone Fechar Tente (X) para colapsar o console e volte a ler a documentação.

O console abre no lugar - você fica na mesma página de endpoint o tempo todo, com a documentação ainda visível acima.

Construindo um pedido

O construtor de solicitações é organizado em abas. Quais abas aparecem depende do método HTTP do endpoint:

• Parámetros — parâmetros de caminho e consulta definidos para o endpoint. Os parâmetros exigidos são marcados, e cada um mostra sua descrição da sua especificação.
• Autorização — o método de autenticação e os campos de credenciais para o esquema de segurança do endpoint. Veja Autorizar solicitações no console Teste.
• Cabeçalhos — cabeçalhos de pedido.
• Corpo — a carga útil de solicitação. Esta aba aparece apenas para métodos que ocupam um corpo, como POST, PUT e PATCH. Não é mostrado para pedidos de GET.

À medida que você preenche as abas, o console cria o pedido em segundo plano. Você pode visualizar a solicitação montada a qualquer momento no painel de Solicitação à direita e ver o exemplo de código equivalente no painel de Código .

Trabalhando com o órgão solicitante

Para endpoints que aceitam um corpo, a aba Corpo oferece um editor completo com ferramentas para construir e validar seu payload.

• nenhum / raw — escolha se envia nenhum corpo (none) ou uma carga útil bruta (raw).
• Tipo de mídia — selecione o tipo de conteúdo para o corpo, como application/json.
• Exemplo — insira um payload de exemplo pronto para o endpoint, gerado a partir da sua especificação.
• Preencha a partir do esquema — preencha o editor com um corpo de exemplo construído a partir do esquema de requisição do endpoint. Isso sobrescrive o conteúdo atual do editor.
• Embelezar — reformatar o corpo com a correta indentação, tornando uma carga útil minificada ou bagunçada legível.
• Restaure um corpo recentemente enviado — traga de volta um corpo que você enviou mais cedo nesta sessão. Isso restaura corpos que você realmente enviou, permitindo que você retorne rapidamente a uma carga útil anterior sem precisar digitá-la novamente.
• Alterne o inversão de palavra — enrole linhas longas dentro do editor para que você possa lê-las sem precisar rolar horizontalmente.

Validação contra o esquema

O editor de corpo valida sua carga útil contra o esquema do endpoint enquanto você digita — não apenas para JSON válido, mas para saber se a carga realmente corresponde ao que o endpoint espera.

Isso detecta dois tipos diferentes de problemas:

• Erros de sintaxe — a carga útil não está bem formada, por exemplo, uma vírgula ou dois pontos faltando. Essas aparecem como mensagens como "Dois esperado" ou "Vírgula esperada".
• Erros de esquema — a carga útil é JSON válida, mas não corresponde ao esquema. Por exemplo, se um campo espera um inteiro e você fornece uma string, o editor sinaliza "Tipo incorreto. Esperado...". Fornecer um campo que o esquema não permite é sinalizado como "Propriedade não é permitida."

Quando problemas são encontrados, uma área de validação de problemas de corpo aparece abaixo do editor, mostrando a contagem das edições. Use o Pular para o próximo problema para mover diretamente para cada um no editor e expanda a lista para ver todos os problemas de uma vez.

Isso significa que um payload pode ser JSON perfeitamente válido e ainda assim ser sinalizado — porque o Try It! o verifica contra o esquema real da sua API, detectando incompatibilidades antes de você enviar a requisição, e não depois que o servidor a rejeita.

Enviando o pedido e lendo a resposta

Quando sua solicitação estiver pronta, clique em Enviar solicitação. O console envia uma requisição ao vivo para sua API e mostra o resultado na área de resposta à direita.

A resposta inclui:

• Status — o código de status HTTP retornado, como 200, 401, ou 404.
• Tempo — quanto tempo o pedido levou, em milissegundos.
• Tamanho — o tamanho do corpo de resposta.
• Abas Corpo e Cabeçalho — alternem entre a carga útil de resposta e o conjunto completo de cabeçalhos de resposta retornados pelo servidor.

Você pode redimensionar os painéis de requisição e resposta arrastando o separador entre eles, dando mais espaço para o lado em que você está trabalhando.

Seu trabalho está salvo

Enquanto você trabalha no console, o Try It! preserva sua entrada para que você não a perca ao se mover:

• Parâmetros, cabeçalhos, corpo da solicitação, tipo de mídia selecionado e aba ativa são mantidos enquanto você troca de endpoint e até mesmo que feche e reabra o console durante a mesma sessão.
• Credenciais e a última resposta são mantidas apenas para a sessão ativa e não são mantidas em manobra. Credenciais também são mascaradas na prévia de solicitações para segurança.

Autenticação

Os desenvolvedores fornecem credenciais na aba Autorização , usando o esquema definido pela sua API — chave API, HTTP Basic, HTTP Bearer, OAuth 2.0 ou OpenID Connect. Try It! lê os esquemas da sua especificação OpenAPI e mostra os campos corretos para cada um.

Para detalhes completos sobre cada método — incluindo como definir cada um na sua especificação e como o login OAuth 2.0 funciona no console — veja Autorizando requisições no console Try It.

Uso de variáveis

As variáveis permitem que os desenvolvedores armazenem um valor uma vez e o reutilizem entre endpoints com um {{placeholder}} — útil para valores como um ID ou token que se repetem em várias requisições. Você pode inserir uma variável em qualquer campo, e a pré-visualização do Request mostra que ela foi resolvida até seu valor real.

Para como criar, gerenciar e reutilizar variáveis, veja Usando variáveis no console Try It.

Requisitos para que o Try It! apareça

Try It! só aparece em uma página de endpoint quando seu arquivo de especificação de API define corretamente o seguinte:

• Uma URL de servidor – a servers seção da sua especificação deve conter pelo menos uma URL base válida.
• Uma variável de servidor (opcional) - se usada, a variável deve ser definida junto com a URL.

Se a URL do servidor estiver faltando, o botão Experimente! não será visível no site da Knowledge Base.

Formato correto da URL do servidor

servers:
  - url: https://api.yourdomain.com
    description: Production

Para APIs com múltiplas regiões, defina múltiplas entradas:

servers:
  - url: https://api.yourdomain.com
    description: Global

  - url: https://api.us.yourdomain.com
    description: US region

O que Tryit! não suporta

• Webhooks - Try It! não está disponível para definições de webhooks. As páginas do Webhook mostram o esquema da carga útil e um exemplo, mas não podem enviar requisições de teste.

FAQ