1. Що таке API і навіщо сервісу два входи
— Слухай, ну добре. Мені потрібні дані про справжні поштовхи. А вони взагалі де лежать? Хто їх знає? — Тьома відкидається на стільці й хмуриться в екран.
— Дивись, — пише Льоха. — Будь-яка програма постійно щось запитує в інших. От у тебе на телефоні застосунок погоди — звідки він знає, що сьогодні плюс вісімнадцять і дощ? Сам він погоду не вимірює, у нього термометра немає. Він питає в того, хто вимірює: у якоїсь метеослужби, у її компʼютерів. Із землетрусами так само. Їх по всій планеті фіксують і публікують геологічні служби — наприклад, USGS, геологічна служба США. Реальна організація, справжні датчики. Оце і є твоє джерело реальних даних — не «інтернет узагалі», а конкретна контора, яку можна перевірити.
— Тобто все, що нам потрібно, десь є — бурмоче Тьома. — Біржа, метеослужба… Залишилося змусити їх поділитися.
— То як взяти? — не вгамується він. — Зайду до них на сайт і скопіюю таблицю вручну?
— А ось тут найцікавіше, — відгукується Льоха. — У кожного сервісу зазвичай два різні входи. Один — сайт, для людей. Заходиш, бачиш красиву сторінку: карта, іконки, цифри. Це для твоїх очей. Але програмі твої очі не потрібні — їй потрібні голі дані. Тому є другий вхід — API.
І одразу підбирає образ:
— Уяви велику контору — банк, паспортний стіл. Усередині купа народу, шафи з папками. Ти в усе це не лізеш. Підійшов до віконця, сказав: «Хочу ось це, ось мої дані» — і отримав результат. Як там за стіною все влаштовано — не твоя турбота. Тобі потрібні дві речі: куди підійти і як попросити. API — це таке віконце, тільки для програм.
— Отже, API — це двері, а не сам банк, — повільно повторює Тьома. — За дверима нехай хоч тисяча працівників, а зовні — просте віконце.
— Саме так.
2. Endpoint, запит і відповідь
— А «куди підійти» — це що, конкретна адреса? — питає Тьома.
— Конкретна. Називається endpoint — «кінцева точка». Звичайний рядок, дуже схожий на адресу сайту. У USGS, наприклад, є відкрита адреса «усі землетруси за останню годину»:
https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson— Виглядає як посилання, — зауважує Тьома.
— Так це і є посилання. Тільки веде не на красиву сторінку, а до віконця з даними. І таких віконець у сервісу багато: одне за годину, інше за день, третє — лише для сильних поштовхів. Різні кінцеві точки — різні віконця однієї контори. Запамʼятай ланцюжок: сервіс → у нього є API → в API є кінцеві точки → кожна віддає свій набір даних. І дві речі не плутай: 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.
— Тобто я тепер знаю, до якого віконця підійти і що мені повернуть, — Тьома відкидається на стільці.
— Знаєш, — киває Льоха. — Залишилося зрозуміти, як зробити, щоб до цього віконця ШІ ходив сам, а не ти копіював руками. І як дотягнутися до того, у чого такого зручного віконця взагалі немає. Завтра покажу — там є одна гарна штука.
ПЕРЕЙДІТЬ В ПОВНУ ВЕРСІЮ