Minilição · Português

Como mostrar dados de uma API externa no seu site

Use uma página pronta de consulta de repositórios, adicione um resultado útil com um assistente e verifique respostas normais, ausentes e indisponíveis.

Começar a aula interativaLer as notas da aula

Para quem é esta lição?

Para quem quer informações atuais de outro serviço num site. A página fornecida e um assistente de programação cuidam do código do navegador; você pode se concentrar no resultado.

Antes de começar

O material da oficina fornecido, acesso à internet e uma visualização HTTP local que seu assistente de programação possa iniciar. Este exemplo lê repositórios públicos do GitHub sem token privado; disponibilidade e limites de solicitações do serviço continuam aplicáveis.

Tempo estimado: 14–26 min

Estimativas com os arquivos iniciais e as contas e ferramentas necessárias já prontas. Configuração, filas de publicação e esperas de e-mail ou DNS exigem tempo adicional. As solicitações não autenticadas do GitHub compartilham uma cota baseada no IP; testes repetidos podem atingi-la.

O que você vai aprender

  • Consulte um repositório público real.
  • Mostre um resultado adicional útil com um assistente de programação.
  • Distinga não encontrar o repositório de um serviço indisponível.

Arquivos da oficina

Etapa 1

Abra a consulta pronta

Peça um valor ao serviço em vez de digitar um número fixo na página.

Peça ao assistente para iniciar a pasta public fornecida por HTTP. Use o exemplo octocat / Hello-World do modelo e acione seu botão de consulta.

Compare a identificação e a contagem retornadas do repositório com o resultado do serviço naquele momento. Não fixe um número antigo como se fosse atual.

Um exemplo concreto

Uma contagem de estrelas salva no texto da página não pode mudar quando o repositório muda.

Inicie a página fornecida de consulta a repositórios públicos por HTTP local. Mantenha a renderização segura de texto existente e não adicione um token privado aos arquivos do navegador. Ajude-me a testar um repositório real, um ausente e uma solicitação de serviço com falha. Depois adicione a contagem documentada de itens abertos e ajude a compará-la com a resposta da API. Cuide das alterações de código para mim.

GitHub: obter um repositório

Arquivos desta etapa

Start hereArquivos da oficina

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

Mostre dados de outro serviço

Carregue do GitHub o nome, a descrição e a quantidade de estrelas de um repositório público.

Uma API é uma forma definida de um software solicitar dados ou uma ação. Aqui seu site pede um repositório ao GitHub e recebe JSON em vez de uma página HTML.

Usamos uma operação de leitura pública para você aprender a tratar solicitações sem começar pela autenticação. O resultado pode mudar entre solicitações; é uma observação atual, não um número para fixar no código.

Exemplo resolvido

Para o proprietário octocat e o repositório Hello-World, o caminho da solicitação é /repos/octocat/Hello-World em api.github.com. A página exibe os campos full_name e stargazers_count retornados.

GitHub: obter um repositório

Extra implementation exercise

Qual é a diferença entre copiar uma quantidade de estrelas para o HTML e buscá-la quando o botão é pressionado?

Mostrar uma solução comentada

O HTML copiado mantém o valor antigo até ser editado. Um fetch pede a resposta atual naquele momento, mas precisa de tratamento de carregamento e falha porque o serviço ou a rede podem não responder.

  • Explica quando o valor é obtido.
  • Reconhece que a solicitação externa pode falhar.

Etapa 2

Verifique uma resposta bem-sucedida

Use uma observação que possa comparar com a fonte.

Peça ao assistente para mostrar a resposta pública da API correspondente ao seu repositório de teste e confirme que a página exibe os valores pretendidos. Mantenha o teste público e sem dados sensíveis.

Uma solicitação que retorna erro não deve ser tratada como resultado normal. Você não precisa escrever o código de solicitação e erro para avaliar o resultado visível.

Um exemplo concreto

Valores ilustrativos: full_name = practice/example e stargazers_count = 12 devem virar o nome visível practice/example e 12 estrelas. São valores fictícios para entender a correspondência, não a contagem atual do exemplo GitHub fornecido.

Arquivos desta etapa

Start hereArquivos da oficina

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

Construa e verifique uma solicitação

Codifique a entrada do usuário e examine a resposta antes de usá-la.

Leia public/app.js e execute a página fornecida por HTTP. encodeURIComponent mantém cada valor de proprietário e repositório no seu próprio segmento de caminho. O host é fixo; o visitante não fornece um endpoint arbitrário.

fetch também se resolve em erros HTTP como 404, então aguardar seu resultado não basta. Verifique response.ok e os status relevantes, interprete o JSON e depois valide os campos necessários para o recurso. textContent exibe textos externos como texto.

O trecho curto abaixo ilustra a verificação HTTP genérica. O app.js completo primeiro trata especificamente os 404 e as respostas restritas ou limitadas por cota; depois verifica outros status malsucedidos, interpreta o JSON e valida os campos. Mantenha essa ordem ao acrescentar um campo exibido.

Exemplo resolvido

Uma descrição com sinais de menor e maior deve continuar como texto visível, não virar marcação da página. Um 404 deve exibir uma mensagem de repositório ausente ou sem acesso público, em vez de um cartão vazio de sucesso.

if (!response.ok) throw Error('Request failed');
const data = await response.json();
result.textContent = data.full_name;

Extra implementation exercise

Por que apenas try/catch não detecta toda resposta HTTP malsucedida?

Mostrar uma solução comentada

Erros HTTP ainda podem produzir um objeto Response normal. Verifique status/ok e lance ou trate o erro antes de considerar seu corpo como o repositório solicitado.

  • Sabe que fetch pode se resolver com 404 ou 500.
  • Verifica o status antes de exibir sucesso.

Etapa 3

Experimente estados ausentes e indisponíveis

Mantenha falhas diferentes compreensíveis.

Experimente um nome de repositório que não existe. Com seu assistente, teste também uma solicitação bloqueada ou com falha na página local de prática. Mantenha a consulta digitada disponível para correção ou nova tentativa.

A página deve distinguir um repositório ausente de uma falha temporária do serviço. Não adicione um token privado no navegador para contornar um limite de solicitações.

Um exemplo concreto

“Repositório não encontrado” e “Serviço indisponível; tente novamente” indicam próximas ações diferentes ao visitante.

GitHub: limites de solicitações da API REST

Arquivos desta etapa

Start hereArquivos da oficina

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

Torne os estados de falha distinguíveis

Repositório ausente, falta de rede e cota esgotada são problemas diferentes.

Teste um repositório público real, um nome claramente inexistente e o modo offline do navegador. A interface limpa o resultado antigo antes de uma nova solicitação, impede envios duplicados e reabilita o botão depois.

O GitHub pode rejeitar solicitações sem autenticação por limites baseados no IP. Não resolva isso colocando um token privado no navegador. Para uso autenticado contínuo, use as credenciais em uma rota controlada de servidor e aplique cache quando adequado.

Exemplo resolvido

Se um cartão de sucesso permanece visível abaixo de “Not found” (não encontrado), o visitante pode confundir dados antigos com a nova consulta. Limpar o resultado anterior deixa inequívoco o estado da solicitação atual.

GitHub: limites de solicitações da API REST

Extra implementation exercise

Uma consulta falha depois de muitos testes. A interface deve informar que o repositório tem zero estrelas?

Mostrar uma solução comentada

Não. Zero é um valor real de dados. Informe que os dados estão indisponíveis ou restritos e examine o status; a quantidade é desconhecida até uma resposta bem-sucedida fornecê-la.

  • Não transforma dados indisponíveis em zero.
  • Verifica o status da solicitação e as evidências de cota.

Etapa 4

Adicione um resultado útil

Descreva a nova informação e deixe o assistente conectá-la.

Peça ao assistente para adicionar open_issues_count ao lado do resultado e identificá-lo como issues e pull requests abertos. Esse total do GitHub inclui as duas categorias; não deve ser rotulado só como bugs. Use a referência fornecida depois de tentar sua versão.

Compare o valor mostrado com a resposta real e repita os testes de sucesso, ausência e indisponibilidade. Você avalia o significado e os estados observados; o assistente cuida da implementação.

Um exemplo concreto

Um open_issues_count fictício de 5 pode representar duas issues e três pull requests abertos. Um rótulo de 5 bugs afirmaria algo que o campo não comprova.

Arquivos desta etapa

Start hereArquivos da oficina

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

Sua tarefa: acrescentar um campo útil do repositório

Acrescente uma quantidade de issues preservando limites claros entre dados e erros.

Exiba open_issues_count depois de validar que é um número finito. Observe que a contagem de repositório do GitHub inclui pull requests, conforme documentado; não a apresente como uma contagem exata apenas de relatos de bugs.

Registre uma consulta bem-sucedida, um repositório ausente e uma tentativa offline. Inclua o que o visitante vê durante a solicitação e depois de cada resultado.

Exemplo resolvido

Um rótulo como “Open issues and pull requests” (issues e pull requests abertos) explica o que o valor mede com mais precisão do que “Bugs”.

O roteiro completo de referência está em reference/assignment-walkthrough.txt. Compare as etapas com seu resultado; preencha o registro de teste com observações do seu próprio projeto.

Extra implementation exercise

Amplie o resultado com a contagem documentada de itens abertos e demonstre os três estados.

Mostrar uma solução comentada

Acrescente open_issues_count aos campos validados após o tratamento dos status bem-sucedidos. Exija um número finito e use o rótulo 'Open issues and pull requests', porque esse campo de repositório do GitHub inclui os dois. O script completo de referência mantém a exibição por textContent e os estados existentes de carregamento e erro.

Dados de exemplo: full_name='sample/site', stargazers_count=3, open_issues_count=2 produz 'sample/site — 3 stars — 2 open issues and pull requests'. O resultado mostra três estrelas e dois itens abertos entre issues e pull requests; não afirma que ambos são bugs.

Teste novamente um repositório público válido, um 404 e o modo offline. Limpe o cartão anterior no começo da próxima consulta; um erro não deve manter contagens antigas nem substituir dados indisponíveis por zero.

  • Valida o número acrescentado e o identifica com precisão.
  • Nenhum sucesso antigo permanece depois de uma nova consulta falhar.

Esta lição foi útil?

Deixe uma curtida ou compartilhe com alguém que possa aproveitar.

Continue aprendendo

Explore as outras lições