Primi passi con le richieste HTTP in Python per le API REST

Effettuare richieste GET e POST con il modulo requests di Python

Hai fretta? Ecco la sintassi Python per effettuare una semplice richiesta GET e POST:

1. Richiesta 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. Richiesta 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())

Capire le API REST e le loro basi HTTP

Abbiamo stabilito che le API sono mediatori software. Un altro modo di pensarle è come un tipo di interfaccia software che concede ad altre applicazioni l’accesso a dati e metodi specifici. 

Una delle architetture più popolari per costruire API è il modello REpresentational State Transfer (REST). Il design architetturale REST consente al client e al server di essere implementati in modo indipendente l’uno dall’altro senza doversi conoscere a vicenda. Ciò significa che il codice su entrambi i lati può essere modificato senza preoccuparsi di come il cambiamento influenzerà l’altro. 

Le API REST, quindi, seguono un insieme di linee guida pensate per semplificare la comunicazione tra software, rendendo così più semplice e logico il processo di accesso ai dati. Non preoccuparti se non conosci queste linee guida; non ti servono per iniziare – ciò che devi sapere è come i dati vengono esposti dai servizi REST. 

I dati dei servizi web REST sono esposti su internet tramite un URL pubblico, accessibile inviando una richiesta HTTP.  

Panoramica dei metodi di richiesta HTTP

Torniamo alla nostra analogia del ristorante: per ordinare, il cameriere si avvicina e tu dici cosa vuoi. Il cameriere passa la tua richiesta allo chef, che prepara il piatto e lo riconsegna tramite il cameriere. In altre parole, lo chef non cucinerebbe finché non riceve la richiesta. 

Le API REST sono uguali: ascoltano i metodi di richiesta HTTP prima di agire. HTTP definisce un insieme di metodi di richiesta che dicono all’API quali operazioni eseguire su una determinata risorsa. Specifica come interagire con le risorse situate all’endpoint fornito. 

Esistono diversi metodi HTTP, ma cinque sono comunemente usati con le API REST: 

È molto probabile che, nell’analisi dei dati e nella data science, eseguirai richieste GET più di qualsiasi altro metodo. Questo perché è il metodo necessario per accedere a determinati dataset. Scopri di più nel corso di DataCamp Intermediate Importing Data in Python.

Quando invii una richiesta a un server web, l’API restituisce una risposta. Alla risposta è associato un codice di stato HTTP. Lo scopo del codice di stato è fornire informazioni aggiuntive sulla risposta, in modo che il client sappia che tipo di richiesta è stata ricevuta.

Cosa sono gli endpoint API?

Un URL definisce i dati con cui interagisci su un server web. Proprio come l’URL di una pagina web è collegato a una singola pagina, un URL di endpoint è collegato a particolari risorse all’interno di un’API. Pertanto, un endpoint può essere descritto come una posizione digitale in cui un’API riceve richieste su una specifica risorsa presente sul suo server — pensalo come l’altra estremità di un canale di comunicazione. 

Per aggiungere contesto, le API REST espongono un insieme di URL pubblici a cui le applicazioni client possono effettuare richieste per accedere alle risorse del servizio web. Gli URL pubblici esposti dall’API REST sono chiamati “endpoint”.

Usare Python per effettuare richieste HTTP

Il modulo requests di Python permette agli sviluppatori di scrivere codice per interagire con le API REST. Consente di inviare richieste HTTP in Python senza doversi preoccupare delle complessità che di solito accompagnano tali attività (cioè aggiungere manualmente query string agli URL, codificare in formato form i dati PUT e POST, ecc.). 

Pur essendo considerato lo standard de facto per effettuare richieste HTTP in Python, il modulo requests non fa parte della libreria standard di Python – va installato. 

Il modo più semplice per installare il modulo requests è con pip: 

python -m pip install requests

È sempre consigliato gestire i pacchetti Python richiesti per i diversi progetti usando ambienti virtuali; in questo modo, i pacchetti di un progetto non interferiranno né romperanno strumenti di sistema in altri progetti perché sono isolati, invece di essere installati globalmente. 

Ora che abbiamo installato il modulo requests, vediamo come funziona. Segui il codice in questo DataLab workbook. 

Effettuare una richiesta GET in Python

Abbiamo già stabilito che GET è uno dei metodi di richiesta HTTP più comuni che incontrerai lavorando con le API REST. Ti permette (come client) di recuperare dati dai server web. 

È importante notare che GET è un’operazione in sola lettura, quindi è adatta solo per accedere a risorse esistenti e non dovrebbe essere usata per modificarle. 

Per dimostrare come funziona il modulo requests, useremo JSONPlaceholder, un’API fittizia liberamente disponibile per test e prototipazione. 

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'}
"""

Nel codice sopra abbiamo eseguito quanto segue: 

1. Definito l’endpoint dell’API da cui recuperare i dati.

2. Usato il metodo requests.get(url) per recuperare i dati dall’endpoint definito. 

3. Usato il metodo response.json() per memorizzare i dati della risposta in un oggetto dizionario; nota che questo funziona solo perché il risultato è in formato JSON – altrimenti sarebbe stato sollevato un errore.   

4. L’ultimo passaggio è stampare i dati JSON della risposta. 

Possiamo anche controllare il codice di stato restituito dall’API in questo modo: 

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

"""
200
"""

Puoi anche passare argomenti a una richiesta GET in Python. Per farlo, dobbiamo modificare leggermente il codice sopra. Ecco come appare il nuovo codice:

# 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'}
"""

Ecco cosa abbiamo fatto diversamente: 

1. Modificato l’endpoint dell’API. Nota che non ha più un 1 alla fine. 

2. Definito il payload in un dizionario.  

3. Passato il payload all’argomento param del metodo requests.get(). 

4. Questo ha restituito un oggetto lista, quindi abbiamo iterato sulla lista e stampato ciascun elemento su una nuova riga. 

Effettuare una richiesta POST in Python

Le richieste GET ti permettono di recuperare dati; le richieste POST ti consentono di creare nuovi dati. Vediamo come possiamo creare nuovi dati sul server 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.'}
"""

Nel codice sopra abbiamo eseguito quanto segue: 

1. Creato una nuova risorsa da aggiungere all’API JSONPlaceholder.

2. Definito l’endpoint su cui effettuare il POST dei nuovi dati.

3. Inviata una richiesta POST usando il metodo requests.post(). Nota che il parametro json è stato impostato nel metodo post(); lo facciamo per indicare all’API che stiamo esplicitamente inviando un oggetto JSON all’URL specificato. 

4. Usato il metodo response.json() per memorizzare i dati della risposta in un oggetto dizionario.

5. L’ultimo passaggio è stampare i dati JSON della risposta. 

Ma, aspetta!

Prima di leggere il prossimo pezzo di codice, prenditi 20 secondi per pensare a quale codice di stato restituirà l’API. 

Ricorda: questa volta abbiamo creato una nuova risorsa invece di limitarci a recuperarla. 

Ok, ecco qui… 

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

"""
201
"""

Argomenti avanzati sulle richieste HTTP in Python

Effettuare richieste HTTP con Python è generalmente semplice; tuttavia, a volte è inevitabile richiedere una configurazione più avanzata o imbattersi in problemi. Ecco alcune sfide che potresti incontrare e come risolverle. 

Autenticare le richieste HTTP

Finora, le nostre interazioni con la REST API sono state piuttosto semplici. L’API JSONPlaceholder non richiede alcuna autenticazione per iniziare a interagirci. Tuttavia, ci sono diversi casi in cui una REST API può richiedere l’autenticazione prima di concedere l’accesso a specifici endpoint – soprattutto quando tratti dati sensibili. 

Per esempio, se vuoi creare integrazioni, recuperare dati e automatizzare i tuoi flussi di lavoro su GitHub, puoi farlo con la GitHub REST API. Tuttavia, molte operazioni sulla GitHub REST API richiedono l’autenticazione, come il recupero di informazioni pubbliche e private sugli utenti autenticati. 

Ecco una semplice soluzione usando il modulo requests di 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
"""

Nel codice sopra abbiamo:

1. Importato l’oggetto HTTPBasicAuth da requests.auth. Questo oggetto allega l’autenticazione HTTP basic alla richiesta data — è essenzialmente come digitare nome utente e password su un sito web. 

2. Definito l’endpoint URL privato da accedere.

3. Istanziato una variabile con un nome utente GitHub – abbiamo anonimizzato il nome utente per privacy.

4. Istanziato una variabile con un personal access token di GitHub per l’autenticazione.  

5. Recuperato i dati dal nostro endpoint e memorizzati nella variabile private_url_response. 

6. Mostrato il codice di stato.  

Gestire gli errori delle richieste HTTP

Ci sono casi in cui le richieste a un’API non vanno come previsto. Possono intervenire diversi fattori, lato client o lato server. Indipendentemente dalla causa, l’esito è sempre lo stesso: la richiesta fallisce. 

Quando usi le API REST, è sempre una buona idea rendere il tuo codice resiliente. Tuttavia, prima di poter scrivere codice robusto, devi capire come gestire gli errori segnalati quando le cose non vanno secondo i piani.  

Per questa dimostrazione, torniamo all’API JSONPlaceholder. Inizieremo scrivendo del codice e poi spiegheremo cosa sta succedendo.  

# 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
"""

Nel codice sopra: 

1. Abbiamo definito l’endpoint di JSONPlaceholder da cui recuperare i dati, ma abbiamo inserito volutamente un errore di battitura nell’URL – questo genererà un errore 404. 

2. Abbiamo usato la gestione delle eccezioni integrata di Python per try e except (catturare) eventuali errori che si verificano tentando di visitare l’endpoint di JSONPlaceholder. Nota che il metodo raise_for_status() è ciò che viene usato per restituire un oggetto HTTPError quando si verifica un errore durante il processo.

3. E infine, abbiamo stampato l’errore che è stato sollevato. 

Sebbene in questo caso abbiamo mostrato come gestire i codici di stato di errore 404, lo stesso schema può essere usato per gestire qualsiasi codice di stato HTTP. 

Gestire un numero eccessivo di redirect

I codici di stato HTTP nella serie 3xx indicano che il client è stato reindirizzato e deve eseguire altre azioni per completare la richiesta. Tuttavia, questo a volte può portare a un loop di redirect infinito.

Il modulo requests di Python fornisce l’oggetto TooManyRedirects per gestire questo problema, come segue: 

"""
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)

Puoi anche impostare il numero massimo di redirect come parametro del tuo metodo di richiesta HTTP: 

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

Un’altra opzione è disabilitare completamente i redirect: 

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

Gestire gli errori di connessione nelle richieste HTTP

Questi sono altri tipi di errori che potresti incontrare quando tenti di inviare richieste a un server. Ci sono diversi motivi per cui potresti non ricevere una risposta dal server (ad es. errore DNS, connessione rifiutata, problemi di connessione a internet, ecc.), ma l’esito è coerente: viene generato un errore di connessione. 

Puoi usare l’oggetto eccezione ConnectionError del modulo requests per intercettare questi problemi e gestirli di conseguenza. 

Ecco come apparirebbe il codice:  

"""
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)

Gestire il timeout delle richieste HTTP

Quando il server API accetta la tua connessione ma non riesce a completare la richiesta entro il tempo consentito, otterrai un “errore di timeout”.

Mostreremo come gestire questo caso impostando il parametro timeout nel metodo requests.get() su un valore estremamente piccolo; questo genererà un errore, che gestiremo usando l’oggetto requests.Timeout. 

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

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

La soluzione più semplice agli errori di timeout è impostare timeout più lunghi. Altre soluzioni possono includere l’ottimizzazione delle richieste, l’inserimento di un ciclo di retry negli script o l’esecuzione di chiamate API asincrone – una tecnica che permette al tuo software di avviare un’attività potenzialmente lunga rimanendo reattivo ad altri eventi invece di aspettare che l’attività sia completata.

Conclusioni

In questo tutorial abbiamo visto cosa sono le API ed esplorato un’architettura comune per le API chiamata REST. Abbiamo anche esaminato i metodi HTTP e come possiamo usare la libreria requests di Python per interagire con i servizi web. 

Dai un’occhiata ai seguenti corsi per sviluppare le tue competenze in data science: 

• Introduction to APIs in Python
• Streamlined Data Ingestion with Pandas 
• Analyzing Social Media Data in Python
• Intermediate Importing Data in Python