API

Algumas partes do seu site respondem a solicitações em vez de mostrar uma página: um formulário de contato que salva uma mensagem, um checkout que solicita um pagamento ao Stripe, uma tarefa que envia os lembretes de amanhã. Cada uma delas é uma rota no código do seu site, e a visualização de API permite testar qualquer uma sem sair do editor.

Como abrir

Quando seu site tem rotas, um seletor Páginas | API aparece no topo do painel de páginas. Clique em API para vê-las.

A lista é organizada como suas páginas, com um nível para cada parte do endereço:

• Uma rota que responde de uma só forma mostra seu método na própria linha, como GET ao lado de health. Clique na linha para abri-la.
• Uma rota que responde de várias formas se expande em uma linha por método, como GET, POST e DELETE.
• As pastas agrupam rotas que compartilham o início do endereço.
• O sitemap, o robots.txt, o manifesto do app e as imagens para redes sociais também aparecem na lista, já que são gerados pelo seu código.

Em um site com muitas rotas, o campo Filtrar endpoints aparece no topo.

Você também pode digitar um endereço que comece com /api/ na barra de endereços no topo do editor ou escolher uma rota na lista que aparece abaixo dela. Digitar um endereço completo como /api/tools/figma abre a rota e preenche figma para você.

No celular, abra o menu do site no topo e escolha API, ou selecione uma rota na lista de páginas.

Como enviar uma solicitação

Escolha um método e a área de edição passa a mostrar a visualização de API. O endereço no topo mostra exatamente o que será enviado e é atualizado conforme você preenche os campos.

• Pré-visualização envia para o rascunho que você está criando. No ar envia para o seu site publicado.
• Enviar envia a solicitação. ⌘↵ / Ctrl+Enter também funciona.

Parâmetros

Os valores que a rota lê do endereço. Os valores de Caminho são as partes entre colchetes, como [id], e são marcados como Obrigatório. Os valores de Consulta são os que vêm depois de ? e que a rota procura. Clique em Adicionar parâmetro para enviar um que não esteja na lista.

Corpo

Para POST, PUT, PATCH e DELETE. Os campos que a rota lê já estão listados, então basta preenchê-los como um formulário. Mude para JSON para escrever o corpo por conta própria. Uma rota que lê um formulário mostra campos de formulário, enviados da mesma forma que um navegador envia um formulário.

Cabeçalhos

Informações extras enviadas junto com a solicitação, como um token de login. Clique em Adicionar cabeçalho para adicionar um.

Como ler a resposta

O status aparece primeiro, junto com o tempo que a solicitação levou e o tamanho da resposta. Abaixo dele:

• Corpo mostra o que foi retornado em um formato fácil de ler: JSON com cores, XML e HTML formatados (com uma visualização de Página para HTML), uma tabela para CSV e imagens.
• Cabeçalhos lista os cabeçalhos que a rota retornou.
• Console mostra o que o servidor do seu site registrou ao responder. Funciona para solicitações enviadas à pré-visualização.

Uma rota que envia um arquivo, como uma exportação CSV ou uma imagem gerada, mostra um botão Baixar. Uma rota que redireciona visitantes informa o destino e mostra Abrir página quando o destino é uma página do seu site.

Clique no relógio para ver as solicitações que você enviou nesta sessão e abrir qualquer uma delas novamente.

Quando algo dá errado

Se o seu código falhar ao responder, a visualização de API mostra o erro e a linha de código em que ele ocorreu.

• Abrir código abre esse arquivo no editor de código.
• Corrigir com IA inicia uma conversa com o erro e os registros do servidor, para que a IA possa corrigi-lo.

Solicitações com login

Algumas rotas só respondem a quem está conectado. Primeiro, envie uma solicitação à rota de login do seu site, com um e-mail e uma senha do site: a visualização de API guarda os cookies definidos pelo site e os envia nas próximas solicitações, como um navegador faz. Eles aparecem em Cabeçalhos como Cookie, com a opção Limpar para sair da conta.

Você também pode adicionar um cabeçalho Authorization por conta própria se suas rotas usarem tokens.

Tarefas agendadas e pagamentos

Você não precisa copiar nenhum segredo para testar estes casos:

• Rotas executadas de forma agendada verificam um segredo que seu site armazena. A visualização de API envia esse segredo para você.
• Os webhooks do Stripe verificam uma assinatura. A visualização de API preenche o corpo com um evento de teste do Stripe e o assina com o segredo do seu próprio site. Eventos de teste assinados só são enviados para Pré-visualização, então um teste nunca afeta pedidos reais no seu site no ar.

Como adicionar uma rota

Clique em + no topo do painel de páginas enquanto estiver em API. Se estiver em Páginas, escolha Novo endpoint no menu.

• Caminho é o endereço da rota depois de /api/. Use [id] para uma parte que muda, como tools/[id]/reviews.
• Métodos são as formas como ela responde. Escolha quantos precisar.
• Descrição permite que a IA escreva a rota em uma nova conversa. Arquivo vazio cria um arquivo em branco para você escrever por conta própria.

A nova rota abre na visualização de API assim que é criada, para você testá-la na hora.

Informações úteis

• Cada solicitação tem 12 segundos. Se uma rota ainda estiver enviando dados depois disso, a visualização mostra o que chegou até aquele momento.
• A visualização de API mostra até 512 KB de uma resposta, e arquivos de até 5 MB podem ser baixados.
• Você pode ter 3 solicitações em andamento ao mesmo tempo e enviar até 30 por minuto.
• Suas solicitações, seu histórico e seus cookies ficam salvos até você recarregar o editor.
• Para enviar para No ar, seu site precisa estar publicado.