Учимся работать с API и следим за МКС

1. Введение

Сегодня почти любое современное приложение использует данные из интернета. Когда вы открываете погоду в телефоне, заказываете такси или читаете новости — это всегда результат работы с API. Программы «разговаривают» друг с другом, обмениваются сообщениями, и чаще всего эти сообщения выглядят в виде простого текста — формата JSON.

JSON (JavaScript Object Notation) стал стандартом для обмена данными между сервисами. Его любят и программисты, и машины: человек легко прочитает текст, а программа легко его разберёт. В JSON всего несколько правил:

• данные хранятся как объекты-словари { "ключ": значение },
• как массивы [значение1, значение2],
• или как простые строки, числа, булевы значения и null.

Например, вот так может выглядеть JSON-объект, описывающий человека:

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

Мы видим ключи (name, age, skills) и их значения. Компактно, наглядно и универсально.

2. Знакомство с API

API (Application Programming Interface) — это «договор» или «контракт», который говорит: если ты обратишься по определённому адресу в интернете и укажешь такие-то параметры, я верну тебе ответ в согласованном формате.

Адрес, по которому мы стучимся для получения данных, называется endpoint. Это просто URL. Часто в нём указываются параметры запроса — так называемые query-параметры.

Например, вот такой URL возвращает прогноз погоды для Минска:

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

Если присмотреться, то после знака ? перечислены параметры:

• latitude = 50.45 — широта,
• longitude = 30.52 — долгота,
• current_weather = true — хотим текущую погоду.

Некоторые API требуют ещё и специальный «пароль» — ключ API. Тогда его добавляют в параметры, например & apikey = ВАШ_КЛЮЧ.

Документацию сервиса с погодой можно посмотреть на сайте open-meteo.com.

3. Как выглядит ответ API?

Когда мы делаем запрос, сервер отвечает нам текстом: JSON-строкой. Иногда это JSON-объект, иногда — JSON-массив.

Пример ответа о погоде:

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

Пример ответа сервиса с координатами МКС:

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

4. Первый пример: получаем погоду

Попробуем написать маленький фрагмент кода, который обратится к бесплатному API погоды open-meteo.com и просто выведет ответ в консоль.

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("HTTP статус: " + resp.statusCode());
System.out.println("Ответ сервера:");
System.out.println(resp.body());

Здесь мы:

1. Создаём HttpClient-клиент.
2. Формируем GET-запрос (HttpRequest).
3. Отправляем его: client.send.
4. Получаем ответ в виде строки: HttpResponse<String>.

Если всё работает, вы увидите HTTP-статус 200 и JSON с погодой.

5. Второй пример: следим за МКС

Теперь обратимся к API open-notify.org, которое в реальном времени показывает координаты Международной космической станции (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());

Результат будет выглядеть так:

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

Прямо сейчас вы получили точные координаты станции, которая летает над Землёй. Если запустить этот код снова через минуту — числа будут уже другими.

6. Полезные нюансы

Когда вы начинаете работать с API, очень важно учитывать несколько вещей.

Во-первых, всегда смотрите на статус ответа: resp.statusCode(). Если это 200 — всё хорошо. Если 404 — значит, адрес неправильный. Если 401 — нужен ключ. Если 429 — вы делаете слишком много запросов.

Во-вторых, помните о лимитах. Бесплатные сервисы ограничивают частоту запросов, чтобы никто не перегружал их серверы.

В-третьих, JSON не всегда будет выглядеть красиво. Иногда это длинная строка в одну линию — это нормально. Позже мы научимся подключать библиотеки (Jackson, Gson), чтобы «разбирать» JSON на поля и работать с ними как с объектами.

Ещё один маленький эксперимент

Возьмём API, которое отдаёт случайный факт о кошках:

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

Запустите этот фрагмент несколько раз, и вы каждый раз будете получать новый JSON с каким-нибудь фактом.