Impariamo a lavorare con le API e monitoriamo la ISS

1. Introduzione

Oggi quasi ogni applicazione moderna utilizza dati da Internet. Quando apri il meteo sul telefono, ordini un taxi o leggi le notizie — è sempre il risultato del lavoro con le API. I programmi «parlano» tra loro, si scambiano messaggi e, il più delle volte, questi messaggi appaiono come testo semplice — nel formato JSON.

JSON (JavaScript Object Notation) è diventato lo standard per lo scambio di dati tra servizi. È apprezzato sia dai programmatori sia dalle macchine: una persona legge facilmente il testo e un programma lo analizza altrettanto facilmente. In JSON ci sono poche regole:

• i dati sono memorizzati come oggetti-dizionario { "chiave": valore },
• come array [valore1, valore2],
• oppure come semplici stringhe, numeri, valori booleani e null.

Ad esempio, così può apparire un oggetto JSON che descrive una persona:

{
  "name": "Alice",
  "age": 25,
  "skills": ["Java", "Python", "SQL"]
}

Vediamo le chiavi (name, age, skills) e i loro valori. Compatto, chiaro e universale.

2. Introduzione alle API

API (Application Programming Interface) — è un «accordo» o «contratto» che dice: se ti rivolgi a un determinato indirizzo in Internet e specifichi certi parametri, ti restituirò una risposta in un formato concordato.

L’indirizzo a cui ci rivolgiamo per ottenere i dati si chiama endpoint. È semplicemente un URL. Spesso in esso si specificano i parametri della richiesta — i cosiddetti parametri di query.

Ad esempio, questo URL restituisce le previsioni meteo per Minsk:

https://api.open-meteo.com/v1/forecast?latitude=50.45&longitude=30.52&current_weather=true

Se guardi bene, dopo il segno ? sono elencati i parametri:

• latitude = 50.45 — latitudine,
• longitude = 30.52 — longitudine,
• current_weather = true — vogliamo il meteo corrente.

Alcune API richiedono anche una «password» speciale — una chiave API. Allora la si aggiunge ai parametri, per esempio & apikey = LA_TUA_CHIAVE.

La documentazione del servizio meteo è disponibile sul sito open-meteo.com.

3. Come appare la risposta di un’API?

Quando inviamo una richiesta, il server risponde con un testo: una stringa JSON. A volte è un oggetto JSON, altre volte — un array JSON.

Esempio di risposta meteo:

{
  "latitude": 50.45,
  "longitude": 30.52,
  "current_weather": {
    "temperature": 21.3,
    "windspeed": 5.2,
    "weathercode": 1
  }
}

Esempio di risposta del servizio con le coordinate della ISS:

{
  "timestamp": 1717590000,
  "iss_position": {
    "latitude": "48.1234",
    "longitude": "12.5678"
  },
  "message": "success"
}

4. Primo esempio: otteniamo il meteo

Proviamo a scrivere un piccolo frammento di codice che si rivolga alla API meteo gratuita open-meteo.com e stampi semplicemente la risposta in console.

String url = "https://api.open-meteo.com/v1/forecast?latitude=50.45&longitude=30.52&current_weather=true";

HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create(url)).GET().build();
HttpResponse<String> resp = client.send(req, HttpResponse.BodyHandlers.ofString());

System.out.println("Stato HTTP: " + resp.statusCode());
System.out.println("Risposta del server:");
System.out.println(resp.body());

Qui facciamo:

1. Creiamo un client HttpClient.
2. Costruiamo una richiesta GET (HttpRequest).
3. La inviamo: client.send.
4. Otteniamo la risposta come stringa: HttpResponse<String>.

Se tutto funziona, vedrai lo stato HTTP 200 e un JSON con il meteo.

5. Secondo esempio: seguiamo la ISS

Ora usiamo l’API di open-notify.org, che mostra in tempo reale le coordinate della Stazione Spaziale Internazionale (ISS).

String url = "http://api.open-notify.org/iss-now.json";

HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create(url)).GET().build();
HttpResponse<String> resp = client.send(req, HttpResponse.BodyHandlers.ofString());

System.out.println(resp.body());

Il risultato apparirà così:

{
  "timestamp": 1717590000,
  "iss_position": {
    "latitude": "48.1234",
    "longitude": "12.5678"
  },
  "message": "success"
}

Proprio adesso hai ottenuto le coordinate esatte della stazione che vola sopra la Terra. Se esegui di nuovo questo codice tra un minuto — i numeri saranno già diversi.

6. Dettagli utili

Quando inizi a lavorare con le API, è molto importante considerare alcune cose.

Per prima cosa, guarda sempre il codice di stato della risposta: resp.statusCode(). Se è 200 — tutto bene. Se è 404 — l’indirizzo è sbagliato. Se è 401 — serve una chiave. Se è 429 — stai facendo troppe richieste.

In secondo luogo, ricorda i limiti. I servizi gratuiti limitano la frequenza delle richieste per evitare il sovraccarico dei server.

In terzo luogo, il JSON non sarà sempre ben formattato. A volte è una riga lunga su una sola linea — è normale. Più avanti impareremo a usare librerie (Jackson, Gson) per «analizzare» il JSON in campi e lavorarci come con oggetti.

Un altro piccolo esperimento

Prendiamo un’API che restituisce un fatto casuale sui gatti:

String url = "https://catfact.ninja/fact";

HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create(url)).GET().build();
HttpResponse<String> resp = client.send(req, HttpResponse.BodyHandlers.ofString());

System.out.println(resp.body());

Esegui questo frammento più volte e ogni volta otterrai un nuovo JSON con qualche fatto.