Primeiros passos com solicitações HTTP Python para APIs REST

Resposta rápida: Fazendo solicitações GET e POST em Python

Você está com pressa? Aqui está a sintaxe Python para você fazer uma solicitação simples para GET e POST:

1. Solicitação GET

import requests

# The API endpoint
url = "https://jsonplaceholder.typicode.com/posts/1"

# A GET request to the API
response = requests.get(url)

# Print the response
print(response.json())

2. Solicitação POST

import requests

# The API endpoint
url = "https://jsonplaceholder.typicode.com/posts"

# Data to be sent
data = {
    "userID": 1,
    "title": "Making a POST request",
    "body": "This is the data we created."
}

# A POST request to the API
response = requests.post(url, json=data)

# Print the response
print(response.json())

Se você quiser se aprofundar na realização de solicitações HTTP com Python e aprender mais sobre APIs REST, continue lendo!

O que é uma API REST?

Estabelecemos que as APIs são mediadores de software. Outra maneira de pensar neles é como um tipo de interface de software que concede a outros aplicativos acesso a dados e métodos específicos. 

Uma das arquiteturas mais populares usadas para criar APIs é o padrão REST (REpresentational State Transfer). O projeto arquitetônico do REST permite que o cliente e o servidor sejam implementados independentemente um do outro, sem que um saiba do outro. Isso significa que o código de ambos os lados pode ser alterado sem que você se preocupe com a forma como a alteração afetará o outro. 

As APIs REST, portanto, seguem um conjunto de diretrizes criadas para simplificar a comunicação entre softwares, tornando o processo de acesso aos dados mais simples e lógico. Não se preocupe se você não conhece essas diretrizes; você não precisa conhecê-las para começar - o que você precisa saber é como os dados são expostos nos serviços REST. 

Os dados dos serviços da Web REST são expostos à Internet por meio de um URL público, que pode ser acessado com o envio de uma solicitação HTTP.  

Visão geral dos métodos de solicitação HTTP

Vamos voltar à nossa analogia do restaurante: para pedir comida em um restaurante, o garçom se aproxima e você diz o que quer. O garçom então passa o seu pedido para o chef, que prepara a refeição e a passa para o garçom para devolvê-la a você. Em outras palavras, o chef não prepararia sua refeição até que sua solicitação fosse enviada. 

As APIs REST são iguais: elas ouvem os métodos de solicitação HTTP antes de agir. O HTTP define um conjunto de métodos de solicitação que informam à API quais operações devem ser executadas para um determinado recurso. Especifica como interagir com os recursos localizados no ponto de extremidade fornecido. 

Há vários métodos HTTP, mas cinco são comumente usados com APIs REST: 

É muito provável que você realize solicitações GET mais do que qualquer outro método em análise e ciência de dados. Isso ocorre porque esse é o método necessário para acessar determinados conjuntos de dados. Saiba mais sobre isso com o curso Intermediário de Importação de Dados em Python do DataCamp.

Quando você faz uma solicitação a um servidor da Web, a API retorna uma resposta. Anexado à resposta está um código de status HTTP. O objetivo do código de status é fornecer informações adicionais sobre a resposta para que o cliente saiba o tipo de solicitação que está sendo recebida.

O que são pontos de extremidade de API?

Um URL define os dados com os quais você interage em um servidor da Web. Assim como o URL de uma página da Web está conectado a uma única página, um URL de endpoint está vinculado a recursos específicos em uma API. Portanto, um endpoint pode ser descrito como um local digital em que uma API recebe consultas sobre um determinado recurso em seu servidor - pense nele como a outra extremidade de um canal de comunicação. 

Para adicionar mais contexto, as APIs REST expõem um conjunto de URLs públicas que podem ser solicitadas por aplicativos clientes para acessar os recursos do serviço da Web. Os URLs públicos expostos pela API REST são conhecidos como "pontos de extremidade".

Usando Python para fazer solicitações HTTP

O módulo Python requests permite que os desenvolvedores escrevam códigos para interagir com APIs REST. Ele permite que você envie solicitações HTTP usando Python sem precisar se preocupar com as complexidades que normalmente acompanham a execução dessas tarefas (ou seja, adicionar manualmente strings de consulta a URLs, codificar formulários PUT e dados POST etc.). 

Apesar de ser considerado o padrão de fato para a realização de solicitações HTTP em Python, o módulo requests não faz parte da biblioteca padrão do Python - ele deve ser instalado. 

A maneira mais simples de instalar o módulo de solicitações é com o pip: 

python -m pip install requests

É sempre recomendável que os pacotes Python necessários para diferentes projetos sejam gerenciados usando ambientes virtuais; dessa forma, os pacotes de um projeto não interferirão e não quebrarão as ferramentas do sistema em outros projetos porque estão isolados, em vez de serem instalados globalmente. 

Agora que instalamos o módulo de solicitações, vamos ver como ele funciona. Acompanhe o código nesta pasta de trabalho do DataLab. 

Fazendo uma solicitação GET em Python

Já estabelecemos que GET é um dos métodos de solicitação HTTP mais comuns que você encontrará ao trabalhar com APIs REST. Ele permite que você (o cliente) recupere dados de servidores da Web. 

É importante observar que GET é uma operação somente de leitura, o que significa que ela só é adequada para acessar recursos existentes e não deve ser usada para modificá-los. 

Para demonstrar como o módulo de solicitação funciona, usaremos o JSONPlaceholder, que é uma API falsa disponível gratuitamente, usada para testes e protótipos. 

import requests

# The API endpoint
url = "https://jsonplaceholder.typicode.com/posts/1"

# A GET request to the API
response = requests.get(url)

# Print the response
response_json = response.json()
print(response_json)

"""
{'userId': 1, 'id': 1, 'title': 'sunt aut facere repellat provident occaecati excepturi optio reprehenderit', 'body': 'quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto'}
"""

No código acima, fizemos o seguinte: 

1. Definiu o ponto de extremidade da API para recuperar dados.
2. Usou o método requests.get(url) para recuperar os dados do ponto de extremidade definido. 
3. Usamos o método response.json() para armazenar os dados de resposta em um objeto de dicionário; observe que isso só funciona porque o resultado é gravado no formato JSON - caso contrário, seria gerado um erro.   
4. A última etapa é imprimir os dados de resposta JSON. 

Também podemos verificar o código de status retornado da API da seguinte forma: 

# Print status code from original response (not JSON)
print(response.status_code)

"""
200
"""

Você também pode passar argumentos para uma solicitação GET do Python. Para fazer isso, precisamos alterar ligeiramente o código acima. Aqui está a aparência do novo código:

# The API endpoint
url = "https://jsonplaceholder.typicode.com/posts/"

# Adding a payload
payload = {"id": [1, 2, 3], "userId":1}

# A get request to the API
response = requests.get(url, params=payload)

# Print the response
response_json = response.json()

for i in response_json:
    print(i, "\n")

"""
{'userId': 1, 'id': 1, 'title': 'sunt aut facere repellat provident occaecati excepturi optio reprehenderit', 'body': 'quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto'}

{'userId': 1, 'id': 2, 'title': 'qui est esse', 'body': 'est rerum tempore vitae\nsequi sint nihil reprehenderit dolor beatae ea dolores neque\nfugiat blanditiis voluptate porro vel nihil molestiae ut reiciendis\nqui aperiam non debitis possimus qui neque nisi nulla'}

{'userId': 1, 'id': 3, 'title': 'ea molestias quasi exercitationem repellat qui ipsa sit aut', 'body': 'et iusto sed quo iure\nvoluptatem occaecati omnis eligendi aut ad\nvoluptatem doloribus vel accusantium quis pariatur\nmolestiae porro eius odio et labore et velit aut'}
"""

Aqui está o que fizemos de diferente: 

1. Você alterou o ponto de extremidade da API. Observe que ele não tem mais um "1" no final. 
2. Definiu a carga útil em um dicionário.  
3. Passou a carga útil para o argumento param do método requests.get(). 
4. Isso retornou um objeto de lista, então percorremos a lista e imprimimos cada item em uma nova linha.  

Fazendo uma solicitação POST em Python

GET permitem que você recupere dados; as solicitações POST permitirão que você crie novos dados. Vamos dar uma olhada em como podemos criar novos dados no servidor JSONPlaceholder.

# Define new data to create
new_data = {
    "userID": 1,
    "id": 1,
    "title": "Making a POST request",
    "body": "This is the data we created."
}

# The API endpoint to communicate with
url_post = "https://jsonplaceholder.typicode.com/posts"

# A POST request to tthe API
post_response = requests.post(url_post, json=new_data)

# Print the response
post_response_json = post_response.json()
print(post_response_json)

"""
{'userID': 1, 'id': 101, 'title': 'Making a POST request', 'body': 'This is the data we created.'}
"""

No código acima, fizemos o seguinte: 

1. Criamos um novo recurso que queríamos adicionar à API JSONPlaceholder.
2. Definiu o ponto de extremidade para POST os novos dados.
3. Você enviou uma solicitação POST usando o método requests.post(). Observe que o parâmetro json foi definido no método post(); fazemos isso para informar à API que estamos enviando explicitamente um objeto JSON para o URL especificado. 
4. Usou o método response.json() para armazenar os dados de resposta em um objeto de dicionário.
5. A última etapa é imprimir os dados de resposta JSON. 

Mas, espere!

Antes de você ler a próxima parte do código, reserve 20 segundos para considerar o código de status que a API retornará. 

Lembre-se: desta vez, criamos um novo recurso em vez de simplesmente recuperá-lo. 

Ok, aqui vai... 

# Print status code from original response (not JSON)
print(post_response.status_code)

"""
201
"""

Você acertou? 

Tópicos avançados de solicitações HTTP do Python

Fazer solicitações HTTP com Python geralmente é simples; no entanto, às vezes é inevitável exigir uma configuração mais avançada ou enfrentar problemas. Aqui estão alguns desafios que você pode encontrar e como resolvê-los. 

Autenticação de solicitações HTTP

Até agora, nossas interações com a API REST têm sido bastante simples. A API JSONPlaceholder não exige nenhuma autenticação para que você comece a interagir com ela. No entanto, há vários casos em que uma API REST pode exigir autenticação antes que o acesso seja concedido a pontos de extremidade específicos, especialmente quando você está lidando com dados confidenciais. 

Por exemplo, se você quiser criar integrações, recuperar dados e automatizar seus fluxos de trabalho no GitHub, poderá fazer isso com a API REST do GitHub. No entanto, há muitas operações na API REST do GitHub que exigem autenticação, como a recuperação de informações públicas e privadas sobre usuários autenticados. 

Aqui está uma solução simples que usa o módulo de solicitações do Python: 

from requests.auth import HTTPBasicAuth

private_url = "https://api.github.com/user"
github_username = "username"
token = "token"

private_url_response = requests.get(
    url=private_url,
    auth=HTTPBasicAuth(github_username, token)
)

private_url_response.status_code

"""
200
"""

No código acima, você pode

1. Importou o objeto HTTPBasicAuth de requests.auth. Esse objeto anexa a autenticação básica HTTP ao objeto de solicitação fornecido - é basicamente o mesmo que digitar seu nome de usuário e senha em um site. 
2. Definiu o endpoint de URL privado a ser acessado.
3. Instanciou uma variável com um nome de usuário do GitHub - anonimizamos o nome de usuário para garantir a privacidade.
4. Instanciou uma variável GitHub com um token de acesso pessoal para autenticação.  
5. Recuperou dados do nosso endpoint e os armazenou na variável private_url_response . 
6. Exibiu o código de status.  

Tratamento de erros de solicitação HTTP

Há casos em que as solicitações feitas a uma API não saem como esperado. Vários fatores no lado do cliente ou do servidor podem estar em jogo. Independentemente da causa, o resultado é sempre o mesmo: a solicitação falha. 

Ao usar APIs REST, é sempre uma boa ideia tornar seu código resiliente. No entanto, antes de escrever um código robusto, você precisa entender como gerenciar os erros relatados quando as coisas não saem como planejado.  

Para esta demonstração, vamos voltar à API JSONPlaceholder. Começaremos escrevendo algum código e depois explicaremos o que está acontecendo.  

# A deliberate typo is made in the endpoint "postz" instead of "posts"
url = "https://jsonplaceholder.typicode.com/postz"

# Attempt to GET data from provided endpoint
try:
    response = requests.get(url)
    response.raise_for_status()
# If the request fails (404) then print the error.
except requests.exceptions.HTTPError as error:
  print(error)

"""
404 Client Error: Not Found for url: https://jsonplaceholder.typicode.com/postz
"""

No código acima: 

1. Definimos o ponto de extremidade do suporte JSONPlace a partir do qual você pode recuperar os dados, mas cometemos um erro de digitação deliberado ao construir o URL - isso gerará um erro 404. 
2. Usamos o tratamento de exceções integrado do Python para try e except (capturar) todos os erros que ocorrem quando você tenta acessar o endpoint JSONPlaceholder. Observe que o método raise_for_status() é usado para retornar um objeto HTTPError quando ocorre um erro durante o processo.
3. E, por fim, imprimimos o erro que foi gerado. 

Embora tenhamos demonstrado como lidar com códigos de status de erro 404 nesse caso, o mesmo formato pode ser usado para lidar com qualquer código de status HTTP. 

Como lidar com muitos redirecionamentos

Os códigos de status HTTP com o formato 3xx indicam que o cliente foi redirecionado e deve executar algumas ações adicionais para concluir a solicitação. No entanto, isso pode ocasionalmente levar a um loop de redirecionamento infinito.

O módulo de solicitações do Python fornece o objeto TooManyRedirects para lidar com esse problema, da seguinte forma: 

"""
Note: The code here will not raise an error
but the structure is how you would hand a case where there
are multiple redirects
"""

url = "https://jsonplaceholder.typicode.com/posts"

try:
  response = requests.get(url)
  response.raise_for_status()
except requests.exceptions.TooManyRedirects as error:
  print(error)

Você também pode definir o número máximo de redirecionamentos como um parâmetro do seu método de solicitação HTTP: 

# Solution 2
url = "https://jsonplaceholder.typicode.com/posts"
session = requests.Session()
session.max_redirects = 3
response = session.get(url)

Outra opção é desativar completamente os redirecionamentos: 

# Solution 3
url = "https://jsonplaceholder.typicode.com/posts"
session = requests.Session()
session.allow_redirects = False
response = session.get(url)

Manipulação de erros de conexão de solicitações HTTP

Esses são outros tipos de erros que você pode enfrentar ao tentar enviar solicitações a um servidor. Há vários motivos pelos quais você pode não receber uma resposta do servidor (por exemplo, falha de DNS, conexão recusada, problemas de conexão com a Internet etc.), mas o resultado é consistente: é gerado um erro de conexão. 

Você pode usar o objeto de exceção requests modules ConnectionError para detectar esses problemas e tratá-los adequadamente. 

Veja como o código ficaria:  

"""
Note: The code here will not raise an error
but the structure is how you would hand a case where there
is a connection error.
"""

url = "https://jsonplaceholder.typicode.com/posts"

try:
  response = requests.get(url)
except requests.ConnectionError as error:
  print(error)

Tratamento do tempo limite das solicitações HTTP

Quando o servidor de API aceita sua conexão, mas não consegue concluir a solicitação dentro do tempo permitido, você receberá um "erro de tempo limite".

Demonstraremos como lidar com esse caso definindo o parâmetro timeout no método requests.get() como um número extremamente pequeno; isso gerará um erro e trataremos esse erro usando o objeto requests.Timeout . 

url = "https://jsonplaceholder.typicode.com/posts"

try:
  response = requests.get(url, timeout=0.0001)
except requests.Timeout as error:
  print(error)

A solução mais simples para os erros de tempo limite é definir tempos limite mais longos. Outras soluções podem incluir a otimização das solicitações, a incorporação de um loop de repetição nos scripts ou a realização de chamadas assíncronas à API - uma técnica que permite que o software inicie uma atividade potencialmente de longa duração enquanto responde a outros eventos, em vez de esperar até que a tarefa seja concluída.

Concluir

Neste tutorial, abordamos o que são APIs e exploramos uma arquitetura de API comum chamada REST. Também examinamos os métodos HTTP e como podemos usar a biblioteca Python requests para interagir com os serviços da Web. 

Confira os cursos a seguir para desenvolver suas habilidades em ciência de dados: 

• Introdução às APIs em Python
• Ingestão de dados simplificada com o Pandas 
• Analisando dados de mídia social em Python
• Importação intermediária de dados em Python