Uczymy się pracy z API i śledzimy ISS

1. Wprowadzenie

Dziś niemal każda nowoczesna aplikacja korzysta z danych z Internetu. Gdy otwierasz pogodę w telefonie, zamawiasz taksówkę albo czytasz wiadomości — to zawsze efekt pracy z API. Programy „rozmawiają” ze sobą, wymieniają się komunikatami i najczęściej te komunikaty mają postać prostego tekstu — formatu JSON.

JSON (JavaScript Object Notation) stał się standardem wymiany danych między serwisami. Lubią go i programiści, i maszyny: człowiek łatwo przeczyta tekst, a program łatwo go przetworzy. W JSON obowiązuje tylko kilka zasad:

• dane są przechowywane jako obiekty (słowniki) { "klucz": wartość },
• jako tablice [wartość1, wartość2],
• albo jako proste napisy, liczby, wartości logiczne i null.

Na przykład tak może wyglądać obiekt JSON opisujący osobę:

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

Widzimy klucze (name, age, skills) i ich wartości. Zwięźle, przejrzyście i uniwersalnie.

2. Pierwsze kroki z API

API (Application Programming Interface) — to „umowa” lub „kontrakt”, który mówi: jeśli zwrócisz się pod określony adres w Internecie i podasz odpowiednie parametry, zwrócę ci odpowiedź w uzgodnionym formacie.

Adres, pod który pukamy, aby uzyskać dane, nazywa się endpoint. To po prostu URL. Często zawiera on parametry zapytania — tak zwane parametry zapytania.

Na przykład taki URL zwraca prognozę pogody dla Mińska:

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

Jeśli się przyjrzeć, po znaku ? wymienione są parametry:

• latitude = 50.45 — szerokość geograficzna,
• longitude = 30.52 — długość geograficzna,
• current_weather = true — chcemy bieżącą pogodę.

Niektóre API wymagają także specjalnego „hasła” — klucza API. Wtedy dodaje się go do parametrów, na przykład & apikey = TWOJ_KLUCZ.

Dokumentację usługi pogodowej można zobaczyć na stronie open-meteo.com.

3. Jak wygląda odpowiedź API?

Gdy wykonujemy zapytanie, serwer odpowiada nam tekstem: JSON-napisem. Czasem jest to obiekt JSON, czasem — tablica JSON.

Przykład odpowiedzi dotyczącej pogody:

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

Przykład odpowiedzi serwisu z koordynatami ISS:

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

4. Pierwszy przykład: pobieramy pogodę

Spróbujmy napisać mały fragment kodu, który odwoła się do bezpłatnego API pogody open-meteo.com i po prostu wypisze odpowiedź w konsoli.

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("Status HTTP: " + resp.statusCode());
System.out.println("Odpowiedź serwera:");
System.out.println(resp.body());

Tutaj:

1. Tworzymy klienta HttpClient.
2. Budujemy żądanie GET (HttpRequest).
3. Wysyłamy je: client.send.
4. Odbieramy odpowiedź jako napis: HttpResponse<String>.

Jeśli wszystko działa, zobaczysz status HTTP 200 i JSON z pogodą.

5. Drugi przykład: śledzimy ISS

Teraz skorzystamy z API open-notify.org, które w czasie rzeczywistym pokazuje współrzędne Międzynarodowej Stacji Kosmicznej (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());

Wynik będzie wyglądał tak:

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

Właśnie otrzymałeś dokładne współrzędne stacji, która przelatuje nad Ziemią. Jeśli uruchomisz ten kod ponownie za minutę — liczby będą już inne.

6. Praktyczne uwagi

Zaczynając pracę z API, warto pamiętać o kilku sprawach.

Po pierwsze, zawsze sprawdzaj status odpowiedzi: resp.statusCode(). Jeśli to 200 — wszystko w porządku. Jeśli 404 — błędny adres. Jeśli 401 — wymagany klucz. Jeśli 429 — zbyt wiele zapytań.

Po drugie, pamiętaj o limitach. Darmowe serwisy ograniczają częstotliwość zapytań, aby nikt nie przeciążał ich serwerów.

Po trzecie, JSON nie zawsze będzie wyglądał ładnie. Czasem to długi jednoliniowy napis — to normalne. Później nauczymy się podłączać biblioteki (Jackson, Gson), aby „rozbierać” JSON na pola i pracować z nimi jak z obiektami.

Jeszcze jeden mały eksperyment

Weźmy API, które zwraca losowy fakt o kotach:

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());

Uruchom ten fragment kilka razy, a za każdym razem otrzymasz nowy JSON z jakimś faktem.