APIs para principiantes: Pedidos de leitura e recolha de dados

Imagine que a sua tarefa consiste em registar, todas as manhãs, o preço de tabela do fornecedor para um candeeiro de secretária. Uma pessoa pode abrir a página do produto e ler essa informação. Um programa precisa de uma forma repetível de identificar o produto e recuperar uma representação que contenha os campos relevantes.

Uma API documentada pode fornecer essa interface. A sua documentação deve indicar-lhe qual a operação que lê os produtos, como funcionam os identificadores, quais as credenciais necessárias e como interpretar os campos. Ainda assim, é necessário verificar a cobertura: uma API suportada pode omitir informações apresentadas no site ou atualizá-las com uma periodicidade diferente.

As APIs para principiantes também devem distinguir as interfaces suportadas dos detalhes de implementação incidentais. As ferramentas de desenvolvimento de um navegador podem revelar os pedidos utilizados por um site, mas essa descoberta não estabelece um contrato público nem autorização para os reutilizar. Dê preferência a uma interface documentada e siga as suas condições de acesso.

A extração de dados (scraping) e o consumo de APIs podem ser entradas para o mesmo fluxo de dados. A extração de dados retira informação de uma apresentação ou documento; o consumo de uma API documentada segue um contrato de software publicado. Nenhuma das duas opções garante automaticamente que um campo esteja atualizado, completo ou adequado para a sua utilização.

Antes de efetuar pedidos, defina o que constitui uma observação bem-sucedida: um produto conhecido, um nome não vazio, o preço numa unidade e moeda conhecidas e a hora em que o recolheu. Essa definição orientará todas as verificações que se seguirem.

Uma solicitação HTTP é mais do que um URL. Inclui um método, um destino, cabeçalhos e, por vezes, um corpo. Cada parte tem uma função. Leia a descrição da operação do fornecedor antes de decidir quais os valores a enviar ou de copiar um exemplo de outro serviço.

O método descreve a semântica da solicitação. O GET é utilizado para recuperação; outros métodos servem a diferentes finalidades. Não deduza os efeitos de um ponto final desconhecido apenas a partir do seu nome. A norma de semântica HTTP define os significados comuns nos quais as implementações se baseiam.

A URL identifica para onde a solicitação é enviada. Um caminho pode identificar um produto ou uma coleção, enquanto os parâmetros de consulta podem fornecer filtros documentados ou valores de paginação. Trate os identificadores e os cursores como dados. Utilize os recursos de construção de URLs do seu cliente ao implementar a solicitação, para que espaços, pontuação e caracteres reservados sejam codificados corretamente.

Os cabeçalhos transportam metadados. Dependendo do contrato, podem indicar formatos aceites, autenticar o cliente ou fornecer condições para uma solicitação. Um corpo transporta conteúdo adicional quando a operação o espera. Colocar um campo no local errado não é equivalente a fornecê-lo corretamente, mesmo que o seu nome pareça correto.

Para o catálogo fictício, elabore uma ficha de trabalho da solicitação em linguagem simples: operação de leitura, filtro de categoria, representação esperada, método de credenciais exigido, tempo limite e comportamento de paginação documentado. Deixe as entradas desconhecidas como questões a esclarecer na documentação. Não as preencha com convenções de outro fornecedor.

Mantenha a ferramenta do cliente em segundo plano em relação a esta ficha de trabalho. Clientes de linha de comandos, bibliotecas Python e SDKs constroem pedidos com diferentes conveniências e predefinições. O nosso guia do cliente HTTP em Python ajuda a comparar a camada de pedidos quando estiver pronto para a implementar.

Mantenha a primeira verificação em ambiente real pequena e apenas de leitura. Utilize o ambiente de teste do fornecedor ou um registo de exemplo autorizado, quando disponível, e, em seguida, analise a resposta antes de alargar o âmbito da solicitação.

Uma resposta HTTP contém um código de estado, cabeçalhos e, possivelmente, um corpo. Uma transferência bem-sucedida e um registo empresarial válido são observações diferentes. O seu coletor deve verificar ambos antes de aceitar os dados.

Um código de estado resume o resultado da solicitação ao nível do HTTP. Um estado de sucesso não garante que o corpo contenha exatamente os campos de que a sua tarefa necessita. Por outro lado, um estado de falha pode incluir um corpo de erro estruturado que explique a ausência de um parâmetro ou a expiração de uma credencial.

Os cabeçalhos ajudam a explicar o corpo. Um tipo de mídia como application/json identifica um formato de representação, mas deve, ainda assim, lidar com conteúdos malformados ou inesperados. Um erro gerado por outro componente pode chegar num formato diferente daquele que solicitou.

O JSON é um formato de texto que contém valores como objetos, matrizes, cadeias de caracteres, números, valores booleanos e nulos. Não é a própria API e não fornece automaticamente significado empresarial. A norma JSON define o formato; o fornecedor define se um determinado campo significa cêntimos, euros, uma data ou outra coisa qualquer.

Ao aprender sobre APIs para principiantes, evite equiparar «analisado com sucesso» a «correto». Verifique os campos obrigatórios, os tipos, as unidades e a identidade após a análise. Distinga também entre valores em falta, nulos, zero e texto vazio. O contrato pode atribuir a cada um deles um significado diferente, e um valor predefinido automático pode apagar essa distinção.

Uma chave de API é uma credencial utilizada por alguns serviços para identificar ou autenticar um utilizador. Outras interfaces utilizam tokens de acesso, pedidos assinados ou mecanismos diferentes. A documentação do fornecedor deve especificar o método necessário e onde a credencial deve ser utilizada.

A autenticação e a autorização respondem a questões diferentes. A autenticação determina quem ou o que está a efetuar a chamada. A autorização determina se esse utilizador pode realizar esta ação neste recurso. Uma chave válida não permite necessariamente o acesso a todos os pontos finais ou aos dados de todas as contas.

No caso do catálogo fictício, um fornecedor pode permitir descrições públicas de produtos, ao mesmo tempo que restringe as quantidades em armazém a determinados clientes. Se a operação de preço for bem-sucedida e a operação de armazém falhar, verifique primeiro as permissões documentadas. Não presuma que uma credencial válida signifique que a segunda solicitação também deva ser permitida.

Mantenha os segredos fora de exemplos de artigos, ficheiros submetidos, capturas de ecrã partilhadas e registos comuns. Utilize uma variável de ambiente ou o mecanismo de segredos aprovado na sua implementação ao implementar um cliente. Registe um identificador de credencial, se necessário para fins de diagnóstico, e não o próprio valor do segredo.

As APIs para principiantes devem deixar clara uma distinção adicional: o ambiente do navegador e um programa do lado do servidor apresentam riscos de exposição diferentes. Um segredo incorporado em código entregue pelo navegador está disponível para a pessoa que utiliza esse navegador. Não o trate como uma credencial mantida no servidor simplesmente porque a variável se chama «private».

Leia o ciclo de vida das credenciais antes de agendar trabalhos. Determine como as credenciais expiram ou são rotacionadas, como o processo obtém substituições e qual o responsável que pode resolver falhas de acesso. Um coletor agendado necessita de um estado de falha claro quando a autenticação deixa de funcionar, em vez de um ciclo que repete o mesmo pedido rejeitado.

Ao partilhar um relatório de problema, inclua a operação, o estado, a hora e os detalhes do erro anonimizados. Esses factos ajudam o fornecedor a investigar sem expor a credencial que dá acesso aos seus dados.

Suponha que o contrato fictício do catálogo indique price_minor é um número inteiro de cêntimos, currency identifica a moeda, e next_cursor é um valor de continuação opaco ou nulo quando este resultado não tiver página seguinte. Estas regras foram inventadas para este exercício e não devem ser assumidas para outra API.

O que se segue é um exemplo de corpo de resposta, não um pedido que deva enviar a qualquer lado:

{
  "items": [
    {
      "id": "lamp-17",
      "name": "Desk lamp",
      "price_minor": 2400,
      "currency": "EUR"
    }
  ],
  "next_cursor": null
}

Comece com a identidade. O item identifica lamp-17, pelo que o seu registo deve preservar esse valor em vez de utilizar a sua posição na matriz como identificador do produto. O nome é um campo separado e pode alterar-se sem criar um produto diferente.

Em seguida, aplique a regra de unidade indicada. O montante é de 24,00 EUR porque este exercício define explicitamente o número inteiro como cêntimos. Sem essa definição, dividir por cem seria um palpite. Mantenha o número inteiro original e a moeda juntamente com qualquer valor de exibição formatado, para que as transformações posteriores continuem a ser explicáveis.

Em seguida, verifique se há continuação. O valor nulo significa que não há página seguinte neste contrato fictício. Isso não prova que todo o inventário do fornecedor contenha apenas um produto; o pedido pode ter selecionado uma categoria ou outro filtro. A completude refere-se sempre a um âmbito de pedido definido.

Por fim, crie mentalmente casos negativos: remova o nome, substitua o número inteiro por uma palavra ou forneça uma moeda inesperada. Decida quais os casos que o seu coletor rejeitaria ou colocaria em quarentena. Um corpo pode continuar a ser JSON válido, mesmo que falhe todas as regras de negócio úteis.

Este exercício capta a essência das APIs para principiantes: sintaxe, significado e aceitação são camadas separadas. Uma implementação real deve tornar essas camadas observáveis, para que uma resposta desconhecida se torne uma falha classificada, em vez de um registo plausível, mas incorreto.

As APIs dividem frequentemente coleções maiores em páginas. O fornecedor pode utilizar números de página, deslocamentos, cursores ou ligações. Aprenda o mecanismo de continuação documentado, em vez de assumir que o incremento de um número recupera tudo.

Um cursor é frequentemente opaco para o consumidor: devolve-se o valor fornecido conforme indicado, sem o interpretar nem modificar. Pode codificar um estado que o fornecedor pode alterar. Um link para a página seguinte permite, de forma semelhante, que o serviço forneça o destino. O guia de arquitetura REST explica por que razão as transições suportadas são importantes numa interface orientada para recursos.

No caso do catálogo fictício, preserve os filtros de pedido juntamente com o valor de continuação. Um cursor para uma categoria pode não se aplicar a outra. Registe as identidades dos itens aceites e defina como as duplicatas são tratadas, especialmente quando um catálogo em constante mudança pode deslocar registos durante a recolha.

Os limites de taxa restringem o volume de pedidos de acordo com a política do fornecedor. Uma 429 Too Many Requests resposta indica uma condição de limite de taxa, mas o estado não define como o fornecedor contabiliza a utilização. A RFC 6585 descreve o código 429 e refere que uma resposta pode incluir Retry-After orientações.

Siga as orientações de atraso aplicáveis e mantenha as tentativas de repetição dentro de limites. Trate um erro de permissão repetido de forma diferente de uma falha temporária do serviço. Considere também o trabalho como um todo: vários colaboradores, cada um a efetuar um número modesto de pedidos, podem, coletivamente, exceder a taxa permitida.

As APIs para principiantes devem incluir uma definição do que constitui «concluído». Chegou à última página documentada, parou devido a um limite de tempo ou falhou após aceitar alguns registos? Guarde essa classificação juntamente com a execução. «Recolheram-se 500 produtos» não revela se o âmbito da solicitação continha 500 ou muitos mais.

Guarde o progresso depois de os dados aceites terem sido armazenados de forma duradoura e conceba o comportamento de reinício de forma a evitar saltar trabalho. Mantenha a janela de recolha na saída, pois uma longa percorrida de uma fonte em mudança pode representar observações ao longo do tempo, em vez de um instantâneo exato.

Uma resposta bem-sucedida prova que uma interação funcionou em condições específicas. Um coletor agendado também deve lidar com dados alterados, acesso expirado, execuções parciais e falhas de saída. Adicione essas responsabilidades de forma deliberada, em vez de aumentar primeiro o volume de pedidos.

Comece com um pequeno relatório de aceitação. Inclua o âmbito do pedido, a hora da recolha, o número de registos aceites, o número de registos rejeitados, o estado de continuação e a categoria de falha, quando aplicável. Evite incluir segredos em bruto ou corpos de resposta sem restrições nesse relatório.

Preserve a diferença entre a recuperação da fonte e a entrega de dados. Se os registos foram aceites localmente, mas a exportação falhou, a recuperação adequada pode consistir em reenviar a saída guardada, em vez de ir buscar novamente a fonte. Uma segunda recuperação pode produzir uma observação diferente e não deve substituir silenciosamente a original.

Decida como funciona a atualidade dos dados. Uma resposta armazenada não é automaticamente atual só porque já foi válida. O cache HTTP tem regras de reutilização e validação, documentadas na RFC 9111. Para o seu conjunto de dados, indique também a antiguidade das observações que os consumidores a jusante podem tolerar.

Teste um conjunto reduzido de falhas antes da programação: uma credencial inválida, um campo obrigatório em falta, um resultado válido vazio e uma execução de paginação interrompida. Utilize fixtures ou um ambiente de teste autorizado, em vez de criar tráfego desnecessário para o fornecedor. Cada caso deve conduzir a um resultado explícito.

As APIs para principiantes transformam-se em engenharia operacional quando esses resultados têm responsáveis. Indique quem lida com problemas de acesso, quem atualiza o mapeamento do esquema e quem decide se uma execução incompleta deve ser entregue. O guia de recolha automatizada liga estas verificações ao agendamento e à recuperação.

Mantenha o primeiro fluxo de trabalho de produção restrito. Um pequeno coletor com âmbito documentado e validação fiável é mais fácil de alargar do que um abrangente, cuja conclusão bem-sucedida esconde dados em falta.

• Leia o contrato de pedido documentado antes de selecionar um cliente, incluindo método, destino, parâmetros, cabeçalhos e credenciais necessárias.
• Verifique separadamente o estado da resposta, o formato de representação e os campos de negócio; um JSON válido não garante um registo de produto válido.
• Mantenha os identificadores, valores originais, unidades e contexto de recolha para que as transformações de dados permaneçam compreensíveis e reversíveis.
• Defina a conclusão da paginação, o tratamento do limite de taxa e o comportamento de reinício antes de assumir que uma solicitação bem-sucedida pode tornar-se uma tarefa agendada.
• Utilize categorias de falha explícitas e proteja os segredos, para que a manutenção não dependa da cópia de registos de pedidos sensíveis.

Não. Uma base de dados armazena e gere dados, enquanto uma API expõe uma interface para utilizar funcionalidades ou informações. Um serviço pode combinar várias bases de dados ou calcular um resultado sem expor esses detalhes. Os utilizadores devem basear-se no contrato da API publicado, em vez de tentarem adivinhar qual a tabela interna que uma resposta representa.

Não necessariamente. Muitas APIs web documentadas podem ser utilizadas por um cliente HTTP do lado do servidor sem a necessidade de renderizar uma página. Os requisitos de autenticação e interação do fornecedor determinam o que é necessário. Um navegador pode ser útil para explorar a documentação, mas a sua presença não substitui a compreensão do contrato de solicitação nem o tratamento correto da resposta.

Não. As condições de acesso variam consoante o fornecedor e o serviço, pelo que deve verificar o plano específico e os termos de utilização. Não presuma que uma solicitação falhada é gratuita ou que um período de teste tenha os mesmos limites que outro plano. Registe as regras de utilização relevantes na integração, para que o trabalho agendado se mantenha dentro do âmbito pretendido.

O seu primeiro marco é um registo que consiga explicar: qual a operação que o forneceu, o que significa cada campo, quando foi observado e por que razão passou na validação. Isso é mais útil do que um script que apresenta um corpo desconhecido e termina com sucesso.

Para um fornecedor real, repita o exercício fictício do catálogo utilizando a documentação deste. Anote os dados de entrada da solicitação, preserve o significado original da resposta e identifique a condição exata que encerra a recolha de dados. Em seguida, teste um caso sem sucesso antes de adicionar mais páginas ou uma programação. Isto mantém as APIs para principiantes alinhadas com um comportamento que pode inspecionar.

Se a informação de que necessita estiver disponível apenas através de páginas web, avalie a API Scraper da WebScrapingAPI como opção de recolha. Aplique os mesmos hábitos a essa entrada: proteja as credenciais, inspecione a resposta, valide o registo extraído e preserve contexto suficiente para que outra pessoa compreenda o resultado.