1. Что такое API и зачем у сервиса два входа
— Слушай, ну хорошо. Мне нужны данные про настоящие толчки. А они вообще где лежат? Кто их знает-то? — Тёма откидывается на стуле и хмурится в экран.
— Смотри, — пишет Лёха. — Любая программа постоянно что-то просит у других. Вот у тебя на телефоне приложение погоды — откуда оно знает, что сегодня плюс восемнадцать и дождь? Само оно погоду не меряет, у него термометра нет. Оно спрашивает у того, кто меряет: у какой-нибудь метеослужбы, у её компьютеров. С землетрясениями так же. Их по всей планете ловят и публикуют геологические службы — например, USGS, геологическая служба США. Реальная организация, настоящие датчики. Вот это и есть твой источник реальных данных — не «интернет вообще», а конкретная контора, которую можно проверить.
— То есть всё что нам нужно где-то есть — бормочет Тёма. — Биржа, метеослужба… Осталось заставить их поделиться.
— Так а как взять-то? — не унимается он. — Захожу к ним на сайт и копирую таблицу руками?
— А вот тут самое интересное, — отзывается Лёха. — У каждого сервиса обычно два разных входа. Один — сайт, для людей. Заходишь, видишь красивую страницу: карта, иконки, цифры. Это для твоих глаз. Но программе твои глаза не нужны — ей нужны голые данные. Поэтому есть второй вход — API.
И тут же подбирает образ:
— Представь большую контору — банк, паспортный стол. Внутри куча народу, шкафы с папками. Ты во всё это не лезешь. Подходишь к окошку, говоришь «хочу вот это, вот мои данные» — и получаешь результат. Как там за стеной всё устроено — не твоя забота. Тебе нужны две вещи: куда подойти и как попросить. API — это такое окошко, только для программ.
— Значит, API — это дверь, а не сам банк, — медленно повторяет Тёма. — За дверью пусть хоть тысяча сотрудников, а снаружи — простое окошко.
— Именно.
2. Endpoint, запрос и ответ
— А «куда подойти» — это что, конкретный адрес? — спрашивает Тёма.
— Конкретный. Называется endpoint — «конечная точка». Обычная строка, очень похожая на адрес сайта. У USGS, например, есть открытый адрес «все землетрясения за последний час»:
https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson— Выглядит как ссылка, — замечает Тёма.
— Так это и есть ссылка. Только ведёт не на красивую страницу, а к окошку с данными. И таких окошек у сервиса много: одно за час, другое за день, третье — только сильные толчки. Разные endpoint'ы — разные окошки одной конторы. Запомни цепочку: сервис → у него API → у API есть endpoint'ы → каждый отдаёт свой набор данных. И две вещи не путай: API — это не сайт, и API — это не «интернет вообще». Это конкретная дверь конкретного сервиса.
— А если я стукнусь по этому адресу — он мне какую-нибудь кракозябру пришлёт? Или excel. В каком виде вообще данные приходят?
— Да не пугайся, никаких кракозябр. Любой разговор с API — это два сообщения туда-сюда, — пишет Лёха. — Ты отправляешь запрос: «дай мне вот это». Сервис присылает ответ: «вот, держи». Всё. Ты этим, кстати, всю жизнь пользуешься — когда браузер открывает страницу, он под капотом делает ровно то же самое: «дай мне страницу по этому адресу». Просто тут в ответ приходит не картинка, а данные.
3. Как читать формат JSON
— Так в каком виде данные-то? — допытывается Тёма.
— Чаще всего в формате JSON. И вот тут заранее не пугайся — проще некуда. JSON — это просто аккуратно подписанный текст. Пары «название: значение». Гляди.
В чат падает маленький пример:
{
"имя": "Хюррем",
"возраст": 30,
"город": "Стамбул"
}— Читается без всякого обучения: имя — Хюррем, возраст — 30, город — Стамбул. Фигурные скобки говорят «вот одна карточка». А если карточек много — их складывают в список, в квадратные скобки. Вот и весь JSON. Это не код, который что-то делает, — это просто способ записать данные. Как таблица, только текстом.
Следом в чате — настоящий ответ USGS, урезанный, чтоб не утонуть:
{
"metadata": {
"title": "Землетрясения за последний час",
"count": 7 // сколько событий пришло
},
"features": [ // список толчков; каждый элемент — одно землетрясение
{
"properties": {
"mag": 4.2, // магнитуда → размер точки
"place": "120 км к ЮЮЗ от Акари, Перу", // место → подпись
"time": 1719230400000 // когда (особый формат времени)
},
"geometry": {
"coordinates": [-74.5, -15.9, 35.0] // [долгота, широта, глубина_км]
}
}
// ... дальше ещё шесть таких же
]
}Тёма подаётся к экрану, водит пальцем по строчкам — и замирает.
— Стоп. Так это же мои поля! mag — магнитуда, place — место, coordinates — координаты. Они тут реально лежат.
— Вот именно, — отзывается Лёха. — Те самые поля, что ты выбрал, когда прикидывал, что показывать на карте, — вот они. Ты заранее решил, что выдёргивать, — и теперь просто берёшь это из features. А данные настоящие именно потому, что спрошены у того, кто их собирает, а не сгенерированы кем-то. И одна честная ловушка на будущее: в координатах сначала идёт долгота, потом широта, а не наоборот, как мы привыкли говорить. Перепутаешь — и точка уедет в океан.
4. Ключи доступа и документация API
— Слушай, а с чего USGS вообще раздаёт это всем подряд? — Тёма недоверчив. — Или так любой сервис можно дёргать?
— Не любой, — отвечает Лёха. — USGS открытый, его окошко бесключевое: подходи и бери, никто не спрашивает, кто ты. Это no-key. Повезло — землетрясения нам отдают даром. Но так не у всех. Многие сервисы хотят знать, кто к ним стучится — чтоб не пускать всех подряд, считать нагрузку, иногда брать деньги за объёмы. Тогда при регистрации тебе выдают ключ доступа, по-английски token — длинную строку из букв и цифр. Твой именной пропуск, и к каждому запросу ты его прикладываешь.
— А у меня такой ключ есть?
— К USGS не нужен, он же открытый. Понадобится — когда полезем к сервису, который просит пропуск. И это уже скоро. А пока заруби одну вещь на будущее: ключ доступа — это как пароль. Кто его получил, тот ходит к сервису от твоего имени, а если ты платишь — то и за твой счёт. Поэтому ключ не показывают кому попало и тем более не суют в первый попавшийся чат. Дойдём до живого ключа — там и потренируешься обращаться с ним правильно.
— Понял. Ключ — это пароль.
— А откуда люди вообще знают, у какой конторы какие адреса и что они возвращают? — спрашивает Тёма. — Где это искать-то?
— В документации, docs. Сервис её сам публикует для тех, кто хочет с ним работать: вот адреса окошек, вот что придёт в ответ, нужен ли ключ. Как инструкция к технике — не угадывай, а открой и посмотри. Хорошая привычка: не гадать, как работает чужой API, а сперва заглянуть в его docs.
— То есть я теперь знаю, к какому окошку подойти и что мне в руки сунут, — Тёма откидывается на стуле.
— Знаешь, — кивает Лёха. — Осталось понять, как сделать, чтоб к этому окошку ИИ ходил сам, а не ты копировал руками. И как дотянуться до того, у чего такого удобного окошка вообще нет. Завтра покажу — есть там одна красивая штука.
ПЕРЕЙДИТЕ В ПОЛНУЮ ВЕРСИЮ