Chamar uma API REST com Python e requests: exemplos práticos

Como usar a biblioteca requests para ler e enviar dados para uma API REST em Python: pedidos GET e POST, JSON, autenticação, erros e novas tentativas automáticas.

Chamar uma API REST com Python e requests: exemplos práticos

Grande parte dos serviços que usamos todos os dias, da previsão do tempo aos programas de gestão empresarial, disponibiliza os seus dados através de uma API. Saber usá-la a partir do Python permite automatizar muitíssimas tarefas: descarregar dados, sincronizar dois serviços, publicar conteúdos, gerar relatórios.

Neste guia usamos o requests, a biblioteca mais difundida para este fim, com exemplos que pode executar de imediato em API públicas e gratuitas.

O que é uma API REST, em resumo

Uma API (Application Programming Interface) é uma forma de um programa pedir dados ou ações a outro programa. As API REST funcionam através da web, com o mesmo protocolo dos sites, o HTTP. Há poucos conceitos a conhecer:

  • Endpoint: o endereço para onde se envia o pedido, por exemplo https://api.example.com/clientes.
  • Método: o tipo de operação. Os principais são GET (ler), POST (criar), PUT ou PATCH (modificar) e DELETE (eliminar).
  • JSON: o formato de texto em que normalmente se trocam os dados. Em Python torna-se um dicionário ou uma lista.
  • Código de estado: um número que indica o resultado. 200 e 201 significam sucesso; 4xx indica um erro no pedido (por exemplo 401 não autorizado, 404 não encontrado, 429 demasiados pedidos); 5xx indica um problema do servidor.

Instalar o requests

Como sempre, convém trabalhar dentro de um ambiente virtual. Com o ambiente ativo:

python -m pip install requests

O primeiro pedido GET: a previsão do tempo

Usamos o Open-Meteo, um serviço meteorológico gratuito que não exige registo. Vamos pedir o tempo atual em Milão:

import requests

URL = "https://api.open-meteo.com/v1/forecast"
params = {
    "latitude": 45.46,
    "longitude": 9.19,
    "current": "temperature_2m,wind_speed_10m",
    "timezone": "auto",
}

response = requests.get(URL, params=params, timeout=10)
response.raise_for_status()

data = response.json()
current = data["current"]
print(f"Temperatura: {current['temperature_2m']} °C")
print(f"Vento: {current['wind_speed_10m']} km/h")

Vejamos as linhas importantes:

  • params: o requests acrescenta os parâmetros ao endereço no formato correto, tratando também espaços e caracteres especiais. Não é preciso compor o URL à mão.
  • timeout=10: se o servidor não responder em 10 segundos, o pedido é interrompido. Sem timeout, um script pode ficar bloqueado para sempre. Defina-o sempre.
  • raise_for_status(): se o código de estado indicar um erro, lança uma exceção em vez de continuar com dados errados.
  • json(): transforma a resposta num dicionário Python.

Um conselho prático: quando trabalhar com uma API nova, imprima a resposta completa com print(data) para ver a sua estrutura antes de extrair os campos que lhe interessam.

Enviar dados com um pedido POST

Para criar algo usa-se o método POST. Para experimentar sem riscos usamos o JSONPlaceholder, um serviço de teste que simula uma API real mas não guarda nada:

import requests

new_post = {
    "title": "Teste",
    "body": "Conteúdo de teste",
    "userId": 1,
}

response = requests.post(
    "https://jsonplaceholder.typicode.com/posts",
    json=new_post,
    timeout=10,
)
response.raise_for_status()

print(response.status_code)   # 201: criado
print(response.json())        # os dados recebidos, com o id atribuído

O parâmetro json= converte o dicionário em JSON e define automaticamente o cabeçalho Content-Type: application/json. É diferente de data=, que envia os dados como um formulário web: se uma API espera JSON, use sempre json=.

Autenticação com um token

As API privadas exigem que se identifique. O método mais comum é um token (ou chave de API) enviado nos cabeçalhos do pedido:

import os
import requests

token = os.environ["API_TOKEN"]
headers = {
    "Authorization": f"Bearer {token}",
    "Accept": "application/json",
}

response = requests.get(
    "https://api.example.com/v1/clientes",
    headers=headers,
    timeout=10,
)

Repare que o token não está escrito no código: é lido de uma variável de ambiente. É uma regra de segurança importante: se o código for parar ao GitHub ou for partilhado, o token continua privado. Para definir a variável antes de executar o script:

# Windows, Linha de Comandos
set API_TOKEN=o-seu-token

# Windows, PowerShell
$env:API_TOKEN = "o-seu-token"

# Linux e macOS
export API_TOKEN="o-seu-token"

O formato exato do cabeçalho (Bearer, Token, uma chave num cabeçalho próprio) depende da API: encontra-o sempre na respetiva documentação.

Tratar os erros

Num script real a rede pode não responder, o servidor pode estar em manutenção, o token pode expirar. Com um bloco try pode tratar cada caso com uma mensagem clara:

import requests

try:
    response = requests.get(URL, params=params, timeout=10)
    response.raise_for_status()
except requests.exceptions.Timeout:
    print("O servidor não respondeu a tempo.")
except requests.exceptions.HTTPError as error:
    print(f"Erro HTTP {error.response.status_code}: {error.response.text[:200]}")
except requests.exceptions.ConnectionError:
    print("Falha na ligação: verifique a rede ou o endereço.")
else:
    data = response.json()
    print(data)

O bloco else só é executado se não tiver havido erros. Imprimir uma parte do texto da resposta (error.response.text) é útil, porque muitas API explicam aí o motivo do erro.

Sessões e novas tentativas automáticas

Se o script fizer muitos pedidos ao mesmo serviço, convém usar uma sessão: reutiliza a ligação (e por isso é mais rápida) e permite definir uma só vez os cabeçalhos e comportamentos comuns. Com uma sessão pode também repetir automaticamente os pedidos que falharam por problemas temporários:

import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

retries = Retry(
    total=3,                     # até 3 novas tentativas
    backoff_factor=1,            # esperas crescentes entre tentativas
    status_forcelist=[429, 500, 502, 503, 504],
    allowed_methods=["GET"],     # repetir apenas as leituras
)

session = requests.Session()
session.mount("https://", HTTPAdapter(max_retries=retries))
session.headers.update({"User-Agent": "meu-script/1.0"})

response = session.get(URL, params=params, timeout=10)
response.raise_for_status()

Porquê repetir apenas os pedidos GET? Porque ler duas vezes não causa danos, ao passo que repetir um POST poderia criar duas vezes o mesmo elemento, por exemplo duas encomendas idênticas.

Boas práticas

  • Defina sempre um timeout, em todos os pedidos.
  • Verifique o código de estado com raise_for_status() antes de usar os dados.
  • Nunca escreva tokens e palavras-passe no código: use variáveis de ambiente.
  • Respeite os limites da API: muitas API limitam o número de pedidos. Se receber um erro 429, abrande; algumas indicam no cabeçalho Retry-After quantos segundos esperar.
  • Trate a paginação: as API que devolvem listas longas dividem-nas em páginas. A documentação indica que parâmetro usar (por exemplo page ou cursor) para pedir as páginas seguintes.
  • Leia a documentação da API: endereços, parâmetros e formato de autenticação variam de um serviço para outro.

E o httpx?

Poderá também encontrar o httpx, uma biblioteca mais recente com uma interface muito semelhante à do requests, que suporta também pedidos assíncronos (ou seja, muitos pedidos em paralelo). Para scripts e automatizações, o requests continua a ser a escolha mais simples; se um dia precisar das funcionalidades assíncronas, a passagem para o httpx será natural.

Fontes oficiais

Partilhar

Qual é a sua reação?

Gosto Gosto 0
Não gosto Não gosto 0
Adoro Adoro 0
Divertido Divertido 0
Irritado Irritado 0
Triste Triste 0
Uau Uau 0