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¤t_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¤t_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());
Здесь мы:
- Создаём HttpClient-клиент.
- Формируем GET-запрос (HttpRequest).
- Отправляем его: client.send.
- Получаем ответ в виде строки: 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 с каким-нибудь фактом.
ПЕРЕЙДИТЕ В ПОЛНУЮ ВЕРСИЮ