Apprenons à utiliser des API et à suivre l’ISS

1. Introduction

Aujourd’hui, presque toute application moderne utilise des données d’Internet. Lorsque vous consultez la météo sur votre téléphone, commandez un taxi ou lisez l’actualité — c’est toujours le résultat d’un travail avec des API. Les programmes « parlent » entre eux, s’échangent des messages, et le plus souvent ces messages prennent la forme d’un texte simple — le format JSON.

JSON (JavaScript Object Notation) est devenu la norme pour l’échange de données entre services. Il plaît autant aux développeurs qu’aux machines : un humain lit facilement le texte, et un programme l’analyse tout aussi facilement. En JSON, il n’y a que quelques règles :

• les données sont stockées comme objets-dictionnaires { "clé": valeur },
• comme des tableaux [valeur1, valeur2],
• ou comme de simples chaînes, des nombres, des valeurs booléennes et null.

Par exemple, voici à quoi peut ressembler un objet JSON décrivant une personne :

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

Nous voyons les clés (name, age, skills) et leurs valeurs. Compact, clair et universel.

2. Découverte des API

Une API (Application Programming Interface) — c’est un « contrat » qui dit : si vous vous adressez à une certaine adresse sur Internet et indiquez tels paramètres, je vous renverrai une réponse dans un format convenu.

L’adresse à laquelle nous nous adressons pour obtenir des données s’appelle un endpoint. C’est simplement une URL. Souvent, elle inclut des paramètres de requête — les paramètres de requête.

Par exemple, cette URL renvoie la prévision météo pour Minsk :

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

Si l’on regarde de près, après le signe ? viennent les paramètres :

• latitude = 50.45 — la latitude,
• longitude = 30.52 — la longitude,
• current_weather = true — nous voulons la météo actuelle.

Certaines API exigent aussi un « mot de passe » — une clé d’API. On l’ajoute alors aux paramètres, par exemple & apikey = VOTRE_CLE.

Vous pouvez consulter la documentation du service météo sur le site open-meteo.com.

3. À quoi ressemble une réponse d’API ?

Quand nous faisons une requête, le serveur nous répond par du texte : une chaîne JSON. Parfois c’est un objet JSON, parfois — un tableau JSON.

Exemple de réponse météo :

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

Exemple de réponse du service avec les coordonnées de l’ISS :

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

4. Premier exemple : récupérer la météo

Essayons d’écrire un petit fragment de code qui appellera l’API météo gratuite open-meteo.com et affichera simplement la réponse dans la 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("Statut HTTP: " + resp.statusCode());
System.out.println("Réponse du serveur:");
System.out.println(resp.body());

Ici, nous :

1. créons un client HttpClient.
2. construisons une requête GET (HttpRequest).
3. l’envoyons : client.send.
4. recevons la réponse sous forme de chaîne : HttpResponse<String>.

Si tout fonctionne, vous verrez le statut HTTP 200 et un JSON avec la météo.

5. Deuxième exemple : suivre l’ISS

Passons maintenant à l’API open-notify.org, qui affiche en temps réel les coordonnées de la Station spatiale internationale (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());

Le résultat ressemblera à ceci :

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

À l’instant, vous avez obtenu les coordonnées exactes de la station qui vole au-dessus de la Terre. Si vous relancez ce code une minute plus tard — les nombres seront déjà différents.

6. Quelques nuances utiles

Lorsque vous commencez à travailler avec des API, il est très important de garder plusieurs points à l’esprit.

Premièrement, regardez toujours le statut de la réponse : resp.statusCode(). Si c’est 200 — tout va bien. Si c’est 404 — l’adresse est incorrecte. Si c’est 401 — il faut une clé. Si c’est 429 — vous effectuez trop de requêtes.

Deuxièmement, souvenez-vous des limites. Les services gratuits limitent la fréquence des requêtes afin que personne ne surcharge leurs serveurs.

Troisièmement, le JSON ne sera pas toujours joliment formaté. Parfois c’est une longue chaîne sur une seule ligne — c’est normal. Plus tard, nous apprendrons à ajouter des bibliothèques (Jackson, Gson) pour « analyser » le JSON en champs et les manipuler comme des objets.

Encore une petite expérience

Prenons une API qui renvoie un fait aléatoire sur les chats :

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

Exécutez ce fragment plusieurs fois, et vous obtiendrez à chaque fois un nouveau JSON contenant un fait quelconque.