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.
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),PUTouPATCH(modificar) eDELETE(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.
200e201significam sucesso;4xxindica um erro no pedido (por exemplo401não autorizado,404não encontrado,429demasiados pedidos);5xxindica 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çalhoRetry-Afterquantos 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
pageoucursor) 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
0
Não gosto
0
Adoro
0
Divertido
0
Irritado
0
Triste
0
Uau
0