Python Requests: Guia Completo de Requisições HTTP

A biblioteca Requests é a ferramenta mais popular do Python para trabalhar com protocolos HTTP. Se você precisa consumir APIs, fazer web scraping, baixar arquivos ou integrar sistemas, o Requests é a escolha ideal pela sua simplicidade e poder.

Neste guia completo, você vai aprender desde a instalação até técnicas avançadas como autenticação, sessões persistentes e tratamento de erros. Ao final, terá domínio completo para trabalhar com qualquer tipo de requisição HTTP em Python.

Instalação e Configuração

O Requests não vem incluso na biblioteca padrão do Python, então você precisa instalá-lo via pip. A instalação é extremamente simples:

# Instalando via pip
pip install requests
Ou usando pip3 em sistemas Linux/Mac
pip3 install requests

Para verificar se a instalação foi bem-sucedida, você pode importar o módulo e verificar sua versão:

import requests
print(requests.version)

A biblioteca é mantida pela comunidade Python e possui excelente documentação oficial. Você pode consultar a documentação completa em requests.readthedocs.io.

Fazendo sua Primeira Requisição GET

A requisição GET é o método mais básico e comum para retrieving dados de um servidor. Com o Requests, fazer uma requisição GET é incrivelmente simples:

import requests
Requisição GET simples
response = requests.get("https://api.github.com")
Verificando o status da resposta
print(f"Status Code: {response.status_code}")
print(f"Reason: {response.reason}")
Visualizando o conteúdo (texto)
print(response.text[:500])

O objeto response contém diversas informações sobre a resposta do servidor:

• status_code: Código HTTP de status (200 = OK, 404 = Not Found, etc)
• reason: Frase descritiva do status ("OK", "Not Found", etc)
• text: Conteúdo da resposta em formato texto
• json(): Conteúdo parsed como JSON
• headers: Cabeçalhos da resposta
• cookies: Cookies recebidos

Verificando Status de FormaSeguro

É uma boa prática verificar se a requisição foi bem-sucedida antes de processar os dados. O Requests facilita isso com o atributo ok:

import requests
response = requests.get("https://api.github.com")
if response.ok:
print("Requisição bem-sucedida!")
data = response.json()
print(data)
else:
print(f"Erro: {response.status_code} - {response.reason}")

Trabalhando com Parâmetros de Query

Muitas APIs utilizam parâmetros de query string para filtrar ou paginar resultados. O Requests permite passar esses parâmetros de forma organizada:

import requests
Parâmetros de query passados como dicionário
params = {
"page": 1,
"per_page": 10,
"sort": "created",
"direction": "desc"
}
response = requests.get(
"https://api.github.com/repos/python/cpython/releases",
params=params
)
print(f"URL gerada: {response.url}")
print(f"Status: {response.status_code}")
Vendo os dados JSON retornados
releases = response.json()
for release in releases[:3]:
print(f"- {release['tag_name']}: {release['name']}")

Esta abordagem é muito mais limpa do que concatenar strings manualmente, pois o Requests trata automaticamente da codificação URL.

Enviando Dados com POST

O método POST é utilizado para enviar dados ao servidor, seja para criar novos recursos, submeter formulários ou enviar payloads JSON:

import requests
Dados para enviar (dicionário Python)
data = {
"username": "usuario_teste",
"email": "[email protected]",
"password": "senha_segura123"
}
Enviando POST com dados de formulário
response = requests.post(
"https://httpbin.org/post",
data=data
)
print(f"Status: {response.status_code}")
print(response.json())

Enviando JSON no Corpo da Requisição

Muitas APIs modernas esperam receber dados no formato JSON. Você pode usar o parâmetro json para isso:

import requests
Payload JSON
payload = {
"title": "Novo Post",
"body": "Conteúdo do post aqui",
"userId": 1
}
response = requests.post(
"https://jsonplaceholder.typicode.com/posts",
json=payload
)
A resposta já vem em JSON automaticamente
result = response.json()
print(f"ID criado: {result['id']}")
print(f"Título: {result['title']}")

O Requests automaticamente define o header Content-Type como application/json quando você usa o parâmetro json.

Headers Personalizados

Em algumas situações, você precisa enviar cabeçalhos personalizados na requisição, como tokens de autenticação, identificação de aplicação ou preferências de formato:

import requests
Definindo headers personalizados
headers = {
"Authorization": "Bearer seu_token_aqui",
"Accept": "application/json",
"User-Agent": "MinhaApp/1.0",
"Accept-Language": "pt-BR,pt;q=0.9"
}
response = requests.get(
"https://api.exemplo.com/dados-protegidos",
headers=headers
)
print(f"Status: {response.status_code}")
print(response.json())

Autenticação com Requests

O Requests suporta diversos métodos de autenticação de forma nativa. Os mais comuns são Basic Auth e Bearer Token:

Basic Authentication

import requests
from requests.auth import HTTPBasicAuth
Autenticação Basic (usuário e senha)
auth = HTTPBasicAuth("usuario", "senha")
response = requests.get(
"https://httpbin.org/basic-auth/usuario/senha",
auth=auth
)
print(f"Status: {response.status_code}")
print(response.text)

Bearer Token (JWT)

import requests
Bearer Token para APIs que usam JWT
headers = {
"Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
response = requests.get(
"https://api.exemplo.com/usuario/perfil",
headers=headers
)
print(response.json())

Para autenticação mais complexa, você pode implementar sua própria classe de autenticação herdando de requests.auth.AuthBase. A documentação oficial sobre autenticação está disponível em docs.python-requests.org.

Trabalhando com Cookies e Sessões

Cookies são fundamentais para manter estado entre requisições, como sessões de usuário. O Requests facilita o trabalho com cookies:

import requests
Verificando cookies da resposta
response = requests.get("https://httpbin.org/cookies")
print("Cookies recebidos:")
print(response.json())
Enviando cookies customizados
cookies = {
"session_id": "abc123xyz",
"user_preference": "dark_mode"
}
response = requests.get(
"https://httpbin.org/cookies",
cookies=cookies
)
print(response.json())

Usando Sessões Persistentes

Quando você precisa fazer múltiplas requisições mantendo os mesmos cookies e configurações, usar uma Session é muito mais eficiente:

import requests
Criar uma sessão
session = requests.Session()
A sessão mantém cookies automaticamente entre requisições
session.headers.update({
"User-Agent": "MeuBot/1.0"
})
Primeira requisição - login
login_data = {"username": "admin", "password": "123456"}
response = session.post("https://exemplo.com/login", data=login_data)
print(f"Login: {response.status_code}")
Segunda requisição - já autenticado
response = session.get("https://exemplo.com/dashboard")
print(f"Dashboard: {response.status_code}")
Terceira requisição - continuar usando a sessão
response = session.get("https://exemplo.com/perfil")
print(f"Perfil: {response.status_code}")

A sessão também permite compartilhar conexões TCP, melhorando a performance em requisições múltiplas. Para mais detalhes sobre sessões, consulte a documentação avançada.

Timeouts e Tratamento de Erros

Por padrão, o Requests espera indefinidamente por uma resposta. É crucial definir timeouts para evitar que sua aplicação trave:

import requests
from requests.exceptions import Timeout, ConnectionError
Timeout de 5 segundos (connect e read)
try:
response = requests.get(
"https://api.exemplo.com/dados",
timeout=5
)
print(response.json())
except Timeout:
print("Tempo limite excedido!")
except ConnectionError:
print("Erro de conexão!")
except requests.exceptions.RequestException as e:
print(f"Erro geral: {e}")

Exceções Disponíveis

O Requests levanta várias exceções que você pode capturar:

• requests.exceptions.RequestException: Classe base para todas exceções
• requests.exceptions.ConnectionError: Erro de conexão de rede
• requests.exceptions.Timeout: Tempo limite excedido
• requests.exceptions.HTTPError: Resposta HTTP com erro (4xx ou 5xx)
• requests.exceptions.TooManyRedirects: Excesso de redirects

Verificando Errors HTTP Automaticamente

Você também pode configurar o Requests para levantar exceções automaticamente em erros HTTP:

import requests
from requests.exceptions import HTTPError
Definir para levantar exceções em status de erro
response = requests.get("https://httpbin.org/status/404")
response.raise_for_status()  # Levanta HTTPError para 4xx/5xx

Download de Arquivos e Stream de Dados

Para arquivos grandes, você não quer carregar tudo na memória de uma vez. O Requests permite fazer streaming de dados:

import requests
Streaming de download - não baixa tudo na memória
url = "https://example.com/arquivo-grande.zip"
response = requests.get(url, stream=True)
Obter tamanho total (se disponível)
total_size = response.headers.get("content-length")
print(f"Tamanho total: {total_size} bytes")
Baixar em chunks
with open("arquivo.zip", "wb") as f:
for chunk in response.iter_content(chunk_size=8192):
if chunk:
f.write(chunk)
print("Download concluído!")

A técnica de streaming é essencial para arquivos grandes ou para processar dados em tempo real. Para download de imagens ou outros arquivos binários, o Requests automaticamente detecta o tipo de conteúdo.

Retry e Retry Strategy

Em aplicações de produção, você frequentemente precisa tentar novamente requisições que falharam temporariamente:

import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
Configurar retry strategy
session = requests.Session()
retry_strategy = Retry(
total=3,
backoff_factor=1,
status_forcelist=[429, 500, 502, 503, 504],
allowed_methods=["GET", "POST"]
)
adapter = HTTPAdapter(max_retries=retry_strategy)
session.mount("http://", adapter)
session.mount("https://", adapter)
Agora as requisições会自动重试
response = session.get("https://api.exemplo.com/dados")
print(f"Status: {response.status_code}")

Esta configuração faz a requisição tentar novamente até 3 vezes, com delay exponencial entre tentativas, apenas para erros de servidor (5xx) ou rate limiting (429).

Timeout Adaptativo com Session

Para aplicações que fazem muitas requisições, você pode configurar timeouts padrão na sessão:

import requests
session = requests.Session()
Configurar timeout padrão para todas as requisições
session.timeout = 10
Timeout específico para uma requisição
response = session.get("https://api.exemplo.com", timeout=30)
print(response.status_code)

Verificação de SSL

Por padrão, o Requests verifica certificados SSL. Em ambientes de desenvolvimento, você pode precisar desabilitar essa verificação:

import requests
Desabilitar verificação SSL (NÃO use em produção!)
response = requests.get(
"https://exemplo.com",
verify=False
)
Para ignorar apenas certificados específicos
response = requests.get("https://exemplo.com", verify="/path/to/cert.pem")

Aviso importante: Nunca desabilite a verificação SSL em ambiente de produção, pois isso expõe sua aplicação a ataques man-in-the-middle.

Integração com Web Scraping

O Requests é frequentemente usado junto com BeautifulSoup para web scraping. Após obter o HTML com Requests, você pode parsear com BeautifulSoup:

import requests
from bs4 import BeautifulSoup
Obter página HTML
response = requests.get("https://exemplo.com/artigos")
response.encoding = "utf-8"
Parsear o HTML
soup = BeautifulSoup(response.text, "html.parser")
Extrair títulos dos artigos
for article in soup.select("article"):
title = article.select_one("h2").text
link = article.select_one("a")["href"]
print(f"{title} -> {link}")

Se você quer aprender mais sobre web scraping, temos um guia completo de web scraping com Python que explora técnicas mais avançadas.

Boas Práticas e Performance

Para usar o Requests de forma eficiente em produção, siga estas práticas:

• Use Session: Reutilize conexões TCP com sessões para melhor performance
• Defina Timeouts: Sempre defina timeouts para evitar travamentos
• Trate Erros: Capture exceções apropriadamente
• Use Retry: Implemente retry com backoff para operações transient failures
• Reuse Connections: Configure connection pooling para muitas requisições
• Log Requests: Adicione logging para debugging em produção