LiçõesComo mostrar dados de uma API externa no seu site

Minilição 16 de 30 · Conectar dados e IA

Abra a consulta pronta

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.

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

Objetivo desta lição

  • 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.
Explicação, exemplo resolvido e prática

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.

Confira os conhecimentos iniciais

São habilidades úteis, não cursos obrigatórios bloqueados. Se já as domina, comece aqui; caso contrário, abra a preparação. Os arquivos fornecidos dispensam um site pessoal anterior.

  1. Como criar seu primeiro site pessoal

    Crie uma apresentação, uma seção de projetos e uma forma de contato a partir do modelo fornecido.

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.

Entenda a ideia

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.

Arquivos desta etapa

Comece aquiArquivos da oficina

Abra ou baixe os arquivos abaixo. Ao salvar o projeto, mantenha as pastas indicadas nos nomes dos arquivos.

Experimente

Qual repositório você consultou e que resultado a página em execução realmente mostrou?

Mostrar uma solução comentada

Registro ilustrativo com contagem inventada: “No momento do teste, consultei octocat / Hello-World. A página retornou octocat/Hello-World e 12 estrelas; a identidade e o número corresponderam à resposta inspecionada.” O 12 é uma medição fictícia do exemplo, não um fato atual sobre esse repositório.

As estrelas podem mudar. Seu registro precisa do número e horário que observou; se o serviço não respondeu, informe esse estado em vez de substituir pela contagem de exemplo.

O que uma boa resposta inclui

  • Identifica o dono/repositório público realmente consultado e a identidade retornada.
  • Relata o número e o horário observados ou a falha exata, sem fixar um valor de exemplo.
Como funciona (opcional)

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

Exercício técnico complementar

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 1 · Como mostrar dados de uma API externa no seu site

Verifique uma resposta bem-sucedida

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

Explicação, exemplo resolvido e prática

Entenda a ideia

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

Comece aquiArquivos da oficina

Abra ou baixe os arquivos abaixo. Ao salvar o projeto, mantenha as pastas indicadas nos nomes dos arquivos.

Experimente

O resultado da página correspondeu à resposta do repositório que você examinou?

Mostrar uma solução comentada

Correspondência ilustrativa com valores fictícios: uma resposta com full_name = practice/example e stargazers_count = 12 deve mostrar practice/example e 12 estrelas. Não deve manter o nome do repositório anterior nem transformar uma contagem ausente em zero.

No teste real, use a resposta real do repositório consultado naquele momento. Uma resposta de limite de solicitações não contém uma contagem normal de estrelas para mostrar.

O que uma boa resposta inclui

  • Compara a identidade e a contagem de estrelas da página com a mesma resposta pública.
  • Não apresenta uma resposta de erro ou um campo ausente como resultado normal de valor zero.
Como funciona (opcional)

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;

Exercício técnico complementar

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 2 · Como mostrar dados de uma API externa no seu site

Experimente estados ausentes e indisponíveis

Mantenha falhas diferentes compreensíveis.

Explicação, exemplo resolvido e prática

Entenda a ideia

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.

Arquivos desta etapa

Comece aquiArquivos da oficina

Abra ou baixe os arquivos abaixo. Ao salvar o projeto, mantenha as pastas indicadas nos nomes dos arquivos.

Experimente

O que os dois casos de falha mostraram e o visitante conseguiu se recuperar?

Mostrar uma solução comentada

Registro ilustrativo de falha: “Um nome inventado mostrou Repository not found or not publicly accessible. Com a solicitação deliberadamente bloqueada no teste local, apareceu um erro; os campos de dono/repositório continuaram disponíveis e o botão permitiu tentar novamente.”

A solicitação bloqueada é uma simulação, não prova de queda real do GitHub. Um limite deve levar a tentar depois, não a colocar um token privado no código público.

O que uma boa resposta inclui

  • Registra resultados distintos para repositório ausente e teste assistido de solicitação com falha.
  • Confere que a consulta continua disponível para corrigir ou repetir, sem adicionar token privado ao navegador.
Como funciona (opcional)

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

Exercício técnico complementar

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 3 · Como mostrar dados de uma API externa no seu site

Adicione um resultado útil

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

Explicação, exemplo resolvido e prática

Entenda a ideia

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

Comece aquiArquivos da oficina

Abra ou baixe os arquivos abaixo. Ao salvar o projeto, mantenha as pastas indicadas nos nomes dos arquivos.

Experimente

Adicione o total de issues e pull requests abertos. Como o valor exibido se comparou à resposta e o que ocorreu nos testes de ausência/indisponibilidade?

O que entregar: A página de consulta atualizada e os resultados observados normais, ausentes e de falha do serviço.

Mostrar uma solução comentada

Correspondência ilustrativa: “Para uma resposta fictícia com open_issues_count = 5, a página mostra 5 issues e pull requests abertos. O total pode conter duas issues e três pull requests; não é uma contagem de cinco bugs.”

Registro ilustrativo: “A consulta normal correspondeu à resposta; o repositório ausente manteve a mensagem de não encontrado; a simulação de bloqueio manteve um erro com nova tentativa.” Sua entrega deve incluir o valor real comparado e indicar verificações não realizadas.

O que uma boa resposta inclui

  • Exibe open_issues_count como issues e pull requests abertos, não somente bugs ou issues.
  • Compara o novo valor com uma resposta e repete os estados normal, ausente e indisponível.
Como funciona (opcional)

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.

Exercício técnico complementar

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.