Padroneggiare le API Python: guida completa per creare e usare API in Python

Le API, ovvero interfacce di programmazione delle applicazioni, sono le vere protagoniste dello sviluppo software moderno. Permettono a sistemi software diversi di comunicare tra loro, rendendo possibile integrare servizi e creare applicazioni. Padroneggiare le API è una competenza importante per chiunque voglia lavorare con i dati in Python, soprattutto se sei uno sviluppatore. Potresti sorprenderti dalle opportunità che si aprono: una volta imparata la competenza, puoi creare applicazioni web, connetterti a servizi esterni o persino usare dati in tempo reale in progetti di machine learning.

In questa guida esploreremo il mondo delle API, impareremo a usarle in Python, a costruirne di nostre con FastAPI e a gestire le sfide comuni che sicuramente incontrerai. Alla fine di questo tutorial avrai una solida comprensione di come usare le API nei tuoi progetti, rendendo il tuo processo di sviluppo più efficiente e le tue applicazioni più potenti. Se dovessi sentirti bloccato tra tutte le informazioni, prova il nostro corso Introduction to APIs in Python, che approfondisce ogni singola parte nel dettaglio.

Che cos'è un'API?

Un'API è come un ponte tra applicazioni software diverse. Consente a queste applicazioni di comunicare e condividere informazioni tra loro.

Immagina un'API come il cameriere in un ristorante. Dici al cameriere cosa vuoi (il tuo ordine) e lui comunica la richiesta alla cucina. La cucina prepara il cibo e il cameriere te lo porta. Allo stesso modo, invii una richiesta a un'API, che la elabora e poi restituisce i risultati.

Per rendere l'idea più concreta, considera alcuni usi reali: potresti, ad esempio, usare un'API pubblica per recuperare dati finanziari per un'analisi di borsa o per accedere a dati meteo in tempo reale per un modello di previsione climatica. Come avrai notato, le API sono particolarmente importanti quando lavori con dataset di grandi dimensioni e/o quando hai bisogno di dati in tempo reale; altrimenti, potresti non avere problemi con l'integrazione.

Come funziona un'API Python. Immagine di Napkin.AI

Usare le API in Python

Usare le API in Python è un modo potente per interagire con servizi esterni, recuperare dati e integrare varie funzionalità nelle tue applicazioni. Python rende il lavoro con le API semplice ed efficiente, principalmente grazie alla libreria requests, che ti consente di inviare richieste HTTP per interagire con le API.

Introduzione alle API in Python

In Python, interagire con le API è un processo lineare grazie alla libreria requests. Questa libreria semplifica l'invio di richieste HTTP, permettendoti di comunicare con le API e recuperare o inviare dati.

Effettuare richieste API in Python

Prima di poter iniziare a effettuare richieste API in Python, ti serve la libreria requests. Puoi installarla con questo comando:

pip install requests

Le basi delle richieste API

Colleghiamo ora il nostro esempio concettuale del ristorante a ciò che avviene effettivamente in Python. Ecco la scomposizione semplificata:

1. Trova il posto giusto: individua l'endpoint dell'API, cioè l'indirizzo web specifico a cui invierai la richiesta.

2. Fai l'ordine: usa la libreria requests di Python per inviare la richiesta all'API. Specificherai che tipo di azione vuoi compiere (ad esempio ottenere dati o inviarli).

3. Ricevi il piatto: l'API restituirà una risposta, che potrai elaborare per estrarre le informazioni di cui hai bisogno.

Richieste GET

Una richiesta GET è il tipo più comune di richiesta HTTP usata per recuperare dati da un server, simile a chiedere informazioni; quando digiti un URL nel browser e premi invio, invii essenzialmente una richiesta GET a quel server, specificando la risorsa desiderata, che il server elabora per trovare e preparare i dati richiesti prima di inviarli indietro in un formato come JSON o XML.

import requestsresponse = requests.get('https://api.example.com/data')data = response.json()print(data)

In questo esempio inviamo una richiesta GET a un'API fittizia e stampiamo la risposta JSON. Le richieste GET vengono comunemente usate per ottenere dati senza modificarli.

Richieste POST

Mentre le richieste GET recuperano dati, le richieste POST inviano istruzioni a un server. Sono spesso usate per creare nuove risorse (come aggiungere un utente) o aggiornare quelle esistenti (come modificare un profilo).

Immagina di compilare un modulo online per registrarti a un servizio. Quando fai clic su Invia, stai essenzialmente inviando una richiesta POST con le tue informazioni. Ecco un esempio semplificato:

# Data to send (like user information)data = {'name': 'John Doe', 'email': '[email protected]'}# Send the data to the API (replace the URL with the actual API endpoint)response = requests.post('https://api.example.com/users', json=data)# Check if the request was successful (usually a status code of 201 for creation)if response.status_code == 201:    print("User created successfully!")else:    print("Error:", response.status_code)

Questo esempio invia un dizionario con le informazioni dell'utente come dati JSON all'API. Poi controlliamo il codice di stato della risposta per verificare se l'utente è stato creato correttamente.

Gestire le risposte

Quando effettui una richiesta API, il server invia una risposta che include due elementi chiave:

• Codice di stato: un numero che indica il successo o il fallimento della richiesta. Ad esempio, 200 di solito significa successo, mentre 404 indica che la risorsa non è stata trovata.
• Dati: le informazioni che hai richiesto, spesso in formato JSON. È qui che risiede il contenuto di valore.

Ecco un esempio in Python:

response = requests.get('https://api.example.com/data')if response.status_code == 200:    data = response.json()    print(data)   else:    print(f"Request failed with status code {response.status_code}")   

Capire i codici di stato delle API Python

I codici di stato delle API sono risposte standardizzate che i server inviano per indicare l'esito della richiesta di un client. Questi codici aiutano gli sviluppatori a capire se una richiesta è andata a buon fine, se si è verificato un errore o se è necessaria un'azione ulteriore.

Codici di stato comuni

• 200 OK: questo codice indica che la richiesta è andata a buon fine. Ad esempio, quando fai una richiesta GET per recuperare dati da un'API, una risposta 200 OK significa che i dati sono stati recuperati correttamente.  

• 404 Not Found: questo codice viene restituito quando il server non riesce a trovare la risorsa richiesta. Per esempio, se provi ad accedere a un endpoint che non esiste, riceverai un errore 404 Not Found.

• 500 Internal Server Error: questo codice segnala che qualcosa è andato storto lato server. È un messaggio di errore generico che può verificarsi per vari motivi, come bug nel codice del server o problemi con il database.

Gestire i diversi codici di stato

Gestire efficacemente i codici di stato API nelle tue applicazioni Python garantisce che il codice si comporti in modo prevedibile e gestisca gli errori con grazia. Se la risposta è 200, procedi con l'elaborazione dei dati restituiti. In caso di errore 404, verifica che l'URL dell'endpoint sia corretto e, se necessario, implementa una logica di fallback o informa l'utente che la risorsa non è disponibile. Per gli errori 500, valuta di riprovare la richiesta dopo un breve intervallo o registra l'errore per ulteriori indagini. Evita però i tentativi eccessivi per non sovraccaricare il server.

Creare API Python

Creare API con Python ti permette di realizzare interfacce applicative potenti ed efficienti. La semplicità di Python e le sue librerie robuste lo rendono un'ottima scelta per lo sviluppo di API.

Introduzione a FastAPI

Ora che sai come usare le API, vediamo come possiamo costruirne di nostre. FastAPI è un framework web moderno e veloce (ad alte prestazioni) per creare API con Python. Come suggerisce il nome, è progettato per essere facile da usare. Una cosa che mi piace di FastAPI è che genera automaticamente documentazione interattiva.

Configurare FastAPI

Per iniziare, ti servono Python e il suo gestore pacchetti, pip, installati. Successivamente, installa FastAPI e Uvicorn, un server ASGI ad alte prestazioni:

pip install fastapi uvicorn

Nota a margine: se riscontri problemi con l'installazione di Python o pip, dai un'occhiata al nostro tutorial: How to Upgrade Python and Pip in Windows, MacOS, and Linux.

Creare una semplice API

Costruiamo un'API essenziale che restituisce un semplice saluto:

from fastapi import FastAPIapp = FastAPI()@app.get("/")def read_root():    return {"Hello": "World"}

Per avviare questa API, esegui il seguente comando:

uvicorn main:app --reload

Questo comando avvia il server Uvicorn, servendo la tua API su http://127.0.0.1:8000. Accedendo a questo URL nel browser otterrai la risposta {"Hello": "World"}.

Funzionalità avanzate di FastAPI

FastAPI non serve solo a creare rapidamente API semplici; offre anche una serie di funzionalità avanzate che lo rendono adatto ad applicazioni complesse e ad alte prestazioni. Ecco alcune capacità chiave: 

Parametri di query

In FastAPI, aggiungere e gestire i parametri di query è semplice grazie all'uso degli hint di tipo di Python. I parametri di query fanno parte dell'URL e servono a passare dati opzionali all'endpoint dell'API, spesso per filtrare o modificare i dati restituiti.

Aggiungere parametri di query

Per aggiungere un parametro di query in FastAPI, lo definisci semplicemente come argomento della funzione dell'operazione di percorso. Se un parametro è opzionale, puoi assegnargli un valore predefinito, come None. Ad esempio, supponiamo di avere un endpoint che recupera elementi da un database. Vuoi permettere agli utenti di filtrare gli elementi con una query di ricerca:

app = FastAPI()@app.get("/items/")def read_items(q: str = None):    if q:        return {"items": ["Item 1", "Item 2", "Item 3"], "query": q}    return {"items": ["Item 1", "Item 2", "Item 3"]}

In questo esempio, q è un parametro di query opzionale. Se forniamo un valore per q, i risultati vengono filtrati in base a quella query. Se q non è fornito, l'endpoint restituisce tutti gli elementi.

Gestire i parametri di query

FastAPI gestisce automaticamente i parametri di query, inclusa la validazione e conversione dei tipi. Ad esempio, se specifichi un parametro di query come intero, FastAPI validerà che l'input sia effettivamente un intero. Se l'input non corrisponde al tipo atteso, FastAPI restituisce un messaggio di errore chiaro.

Ecco un esempio con un parametro di query obbligatorio e la validazione dei tipi:

@app.get("/items/{item_id}")def read_item(item_id: int, q: str = None):    return {"item_id": item_id, "query": q}

In questo caso, item_id è un parametro di percorso e q è un parametro di query opzionale. FastAPI garantirà che item_id sia un intero ed elaborerà il parametro di query q se fornito.

Gestire diversi metodi HTTP

Implementare metodi HTTP diversi come GET, POST, PUT e DELETE è semplice e rispecchia il modo in cui si definiscono le route in altri framework. Ogni metodo è legato a un tipo di operazione specifico, come recuperare dati (GET), creare nuovi dati (POST), aggiornare dati esistenti (PUT) o eliminare dati (DELETE).

Metodo GET

Il metodo GET viene usato per recuperare dati dal server. In FastAPI, definisci un endpoint GET così:

@app.get("/items/")def get_items():    return {"items": ["Item 1", "Item 2", "Item 3"]}

Metodo POST

Il metodo POST viene usato per creare nuovi dati. Puoi definire un endpoint POST e ricevere dati nel corpo della richiesta:

@app.post("/items/")def create_item(item: dict):    return {"item": item}

Metodo PUT

Il metodo PUT viene usato per aggiornare dati esistenti. Di solito richiede sia un identificatore sia i nuovi dati:

@app.put("/items/{item_id}")def update_item(item_id: int, item: dict):    return {"item_id": item_id, "updated_item": item}

Metodo DELETE

Il metodo DELETE viene usato per rimuovere dati. In FastAPI, un endpoint DELETE è definito così:

@app.delete("/items/{item_id}")def delete_item(item_id: int):    return {"message": f"Item {item_id} deleted"}

Autenticazione e sicurezza

FastAPI offre diversi meccanismi per implementare autenticazione e sicurezza:

• HTTP Basic Auth: un metodo semplice, ma in genere non consigliato in ambienti di produzione per motivi di sicurezza.
• API Key: un'opzione più sicura che prevede la generazione di chiavi uniche per i client.
• OAuth 2.0: uno standard complesso ma robusto per l'autorizzazione, comunemente usato per integrazioni di terze parti.
• JSON Web Token (JWT): un approccio diffuso per rappresentare attestazioni in modo sicuro tra due parti.