API: cosa sono, a cosa servono e come usarle

Le applicazioni e i servizi che utilizziamo ogni giorno sono sempre più interconnessi e dipendenti l’uno dall’altro. La capacità di integrare diverse tecnologie e piattaforme è diventata una condizione essenziale per la creazione di soluzioni innovative e competitive. Le API (Application Programming Interface) giocano un ruolo fondamentale, consentendo alle applicazioni di comunicare tra loro e scambiare dati in modo efficiente e sicuro.

Le API sono ormai una componente essenziale della programmazione moderna: la loro importanza continua a crescere con l’avanzare della tecnologia. Sono utilizzate per integrare servizi cloud, piattaforme di social media, sistemi di pagamento e molto altro ancora.

Come funzionano le API

Quando un’applicazione vuole accedere a un’altra applicazione o a un servizio, può inviare una richiesta attraverso l’API, ove disponibile. L’API riceve la richiesta e la elabora, restituendo una risposta che l’applicazione può utilizzare. Il processo è simile al funzionamento di qualunque applicazione client-server; nel caso delle API, tuttavia, queste costituiscono un’interfaccia di programmazione che consente alle applicazioni di comunicare reciprocamente in modo standardizzato.

Le API utilizzano diversi metodi di richiesta per eseguire azioni specifiche. Ad esempio, un’applicazione può utilizzare il metodo GET per recuperare dati; il metodo POST per creare nuovi dati lato server. Questi metodi sono standardizzati e consentono alle applicazioni di comunicare tra loro in modo efficace.

Metodi GET e POST

La richiesta GET è utilizzata per recuperare dati da un server. È il metodo più comune quando si è interessati a leggere informazioni senza modificare nulla sul sistema remoto. Le ottenute possono essere memorizzate nella cache del browser o in altri sistemi di caching, migliorando le prestazioni.

Cosa ancora più importante, i parametri della richiesta sono inclusi nell’URL, il che significa che sono visibili e facili da condividere. Tuttavia, questo limita la quantità di dati che si possono inviare: la lunghezza degli URL è limitata.

La richiesta POST è usata per inviare dati al server, generalmente per creare o aggiornare una risorsa. I dati sono inviati nel corpo della richiesta, il che significa che non ci sono limitazioni significative sulla quantità di dati trasmissibili.

I dati inviati possono in questo caso modificare lo stato del server e, ad esempio, essere utilizzati per creare una nuova risorsa sul sistema remoto.

Gli errori e la gestione delle API

Ma cosa succede quando qualcosa va storto? Quando un’applicazione invia una richiesta attraverso l’API e non riceve la risposta attesa, può verificarsi un errore. Gli errori possono essere causati da diversi fattori, come ad esempio un problema di connessione, un errore di sintassi o un problema di autorizzazione.

Per gestire gli errori, le API utilizzano codici di stato HTTP e messaggi “ad hoc”. Questi codici e messaggi sono standardizzati e consentono alle applicazioni di gestire gli errori in modo efficace.

Le API, ovviamente, non sono tutte uguali. Ogni sviluppatore fornisce le sue ed è essenziale leggere la documentazione per comprendere come funzionano. Questo è essenziale per evitare errori e garantire che l’integrazione sia efficace. In secondo luogo, è bene avvalersi – quando disponibili – degli strumenti di sviluppo per l’API in questione. In questa maniera la procedura di integrazione risulterà molto più semplice.

Dove trovare API pubbliche disponibili gratis

Il sito Free Public APIs contiene una raccolta, continuamente aggiornata e verificata, di API pubbliche utilizzabili gratuitamente. Provate a scorrere la lista cliccando sulla colonna di sinistra: ce n’è per tutti i gusti e per qualsiasi necessità.

Si prenda ad esempio la IP Geolocation API: permette di geolocalizzare IP semplicemente inviando l’indirizzo IP da verificare, in formato IPv4 oppure IPv6. La richiesta GET che segue permette di recuperare tutte le informazioni possibili sull’IP specificato (sostituire 8.8.8.8).

http://ip-api.com/json/8.8.8.8?fields=status,message,continent,continentCode,country,countryCode,region,regionName,city,district,zip,lat,lon,timezone,offset,currency,isp,org,as,asname,reverse,mobile,proxy,hosting,query

Come spiegato nella guida disponibile in questa pagina, si può anche stabilire se un indirizzo IP sia dietro un server proxy, se faccia parte della rete Tor o di qualche piattaforma di hosting/cloud.

Le API generalmente rispondono con una serie di informazioni strutturate in formato JSON. Nel caso di una richiesta GET, basta copiare l’URL nella barra degli indirizzi del browser e verificare la risposta ricevuta.

API pubbliche e private

Le API possono essere pubbliche o richiedere qualche forma di autenticazione per poter essere usate. Le API pubbliche sono accessibili a chiunque e non richiedono alcuna verifica. Molte API, tuttavia, a parte quelle citate al precedente paragrafo necessitano di un token univoco che attesti la legittimità di ogni singola richiesta. In altre parole, solo gli utenti autorizzati possono accedere ai dati o alle funzionalità dell’API.

L’API key è un token univoco utilizzato per autenticare le richieste API. È solitamente una stringa di caratteri alfanumerici generata dal fornitore dell’API e trasferita all’utente che vuole utilizzarla. Attenzione a non farvi scappare l’API key nelle applicazioni distribuite sui dispositivi degli utenti finali!

Quando un utente vuole utilizzare un’API che richiede autenticazione, deve includere l’API key nella richiesta trasmessa. Il provider verifica l’API key e, se è valida, autorizza l’accesso.

A seconda dei casi, l’API key può essere utilizzabile in diversi modi. Ad esempio come parametro nella URL, come intestazione HTTP o come parte integrante del corpo della richiesta.

Per fare un esempio oggi piuttosto comune, i modelli generativi messi a disposizione dai vari fornitori (OpenAI, Anthropic, Google Cloud,…) possono essere interrogati via API in modo da estendere le abilità delle proprie applicazioni arricchendole con funzionalità di intelligenza artificiale. Ecco, questi provider richiedono la stipula di un abbonamento e l’invio di richieste tramite API, previa autenticazione.

Non è necessario, comunque, trasferire i dati sul cloud: Ollama abilita l’utilizzo dei modelli generativi aperti in ambito locale. Configurando il sistema su un server affacciato sulla rete Internet o su una macchina cloud, è possibile usare una pratica e flessibile API per dialogare con i vari Large Language Models (LLM).

Come inviare una query a un’API remota

Uno dei metodi più comuni per inviare una richiesta a un’API da ambiente Windows, consiste nell’utilizzare PowerShell. Si può premere Windows+X quindi scegliere Windows PowerShell oppure Terminale quindi incollare quanto segue (indicando ovviamente l’URL corretto):

$url = "http://ip-api.com/json/8.8.8.8"
$response = Invoke-RestMethod -Uri $url -Method Get
$response

La cmdlet che segue, invece, permette di trasmettere una richiesta POST all’API specificata:

# URL dell'API da invocare
$url = "https://api.example.com/data"

# Dati da inviare con la richiesta POST (in formato JSON)
$body = @{
    "key1" = "value1"
    "key2" = "value2"
} | ConvertTo-Json

# Inviare la richiesta POST
$response = Invoke-RestMethod -Uri $url -Method Post -Body $body -ContentType "application/json"

# Mostrare la risposta
$response

Inviare la richiesta con curl

In Windows, ma anche in qualunque altro sistema, si può usare l’utilità curl per confezionare la richiesta HTTP da inviare all’API di proprio interesse. Ecco un semplice esempio di richiesta GET:

curl -X GET "https://api.example.com/data"

Ed ecco un esempio di richiesta POST, con cui trasferimento delle informazioni che devono essere elaborate lato server, per poi ottenere una risposta:

curl -X POST "https://api.example.com/data" -H "Content-Type: application/json" -d "{\"key1\":\"value1\", \"key2\":\"value2\"}"

Su Linux, supponendo di aver installato l’utilità jq, si può ricorrere al formato seguente

Usare un qualunque linguaggio di programmazione, ad esempio Python

Python permette di gestire le richieste inviate alle API e le loro risposte con semplici script. Nulla vieta di utilizzare un qualunque altro linguaggio per giungere al medesimo risultato, specie se si stesse sviluppando o si fosse realizzata un’applicazione Web che deve dialogare con l’API remota.

Di seguito un esempio di richiesta GET in Python:

import requests

url = "https://api.example.com/data"
response = requests.get(url)
print(response.json())

Segue invece un esempio di richiesta POST:

import requests

url = "https://api.example.com/data"
data = {
    "key1": "value1",
    "key2": "value2"
}

response = requests.post(url, json=data)
print(response.json())

Conclusioni

Le API rappresentano il tessuto connettivo che abilita l’interoperabilità e l’innovazione nel mondo delle applicazioni moderne. Attraverso le API, le applicazioni possono comunicare, condividere dati e funzionalità, estendendo così le loro capacità ben oltre i confini delle singole piattaforme.

Questa interconnessione non solo accelera lo sviluppo software, riducendo tempi e costi, ma favorisce anche l’emergere di ecosistemi digitali complessi e collaborativi. In un mondo sempre più orientato verso l’integrazione e la scalabilità, le API sono il motore che guida la trasformazione digitale, rendendo possibili esperienze utente più fluide, personalizzate ed efficaci.

Credit immagine in apertura: iStock.com – putilich