Первый запрос руками: curl и живой API

Хватит теории — пора сделать первый настоящий запрос к живому API своими руками. Мы возьмём публичный API GitHub (он не требует регистрации для простых запросов) и инструмент curl, который умеет отправлять запросы прямо из терминала. Вы увидите своими глазами, как клиент (ваш терминал) обращается к серверу (GitHub) и получает ответ.

Это связывает воедино две предыдущие теоретические темы. Помните диалог из прошлого урока: адрес -> запрос -> ответ? Сейчас вы проживёте его на практике.

Что такое curl

curl — это маленькая программа для терминала, которая делает ровно одну вещь: отправляет запрос на указанный адрес (URL) и печатает ответ. По сути, это самый честный и простой клиент: ничего лишнего, никакого красивого интерфейса — только запрос и ответ в чистом виде.

curl уже установлен почти везде: на macOS и Linux он есть из коробки, на Windows 10/11 — тоже. Проверим, что он у вас работает:

curl --version

curl 8.4.0 (x86_64-apple-darwin23.0) libcurl/8.4.0
Release-Date: 2023-10-11
Protocols: dns file ftp ftps gopher gophers http https ...

Если вы видите строку, начинающуюся с curl и номером версии — всё готово. Если команда не нашлась, установите curl (на Windows проще всего обновить систему, на Linux — sudo apt install curl).

Первый запрос: дзен GitHub

Начнём с самого простого, что вообще можно попросить у API — с текстовой строчки. У GitHub есть забавный адрес, который возвращает случайную фразу-афоризм про дизайн (так называемый “дзен GitHub”). Идеально для первого запроса: ответ — одна короткая строка текста, ничего сложного.

Выполните в терминале:

curl https://api.github.com/zen

Design for failure.

Поздравляю — вы только что сделали свой первый запрос к API. Разберём, что произошло, через знакомую тройку:

• Адрес (URL): https://api.github.com/zen — мы обратились к серверу GitHub (api.github.com) и попросили ресурс /zen.
• Запрос: curl отправил серверу запрос “дай мне данные по этому адресу”.
• Ответ: сервер вернул одну строку текста — Design for failure. (у вас может быть другая фраза, они случайные — запустите ещё раз и увидите другую).

Запустите команду несколько раз — каждый раз сервер отвечает новой фразой:

curl https://api.github.com/zen

Non-blocking is better than blocking.

Это и есть тот самый диалог клиент-сервер, который мы рисовали стрелочками. Только теперь он реальный и происходит между вашим компьютером и серверами GitHub где-то в дата-центре.

Второй запрос: ответ в формате JSON

Простая строчка — это хорошо для первого шага, но настоящие API почти всегда возвращают данные в структурированном виде. Самый популярный формат — JSON (произносится “джейсон”). Не пугайтесь слова: JSON — это просто текст, организованный в понятные пары “название: значение”. Человек его легко читает, и программа — тоже.

Попросим у GitHub информацию про конкретного пользователя. Возьмём Линуса Торвальдса — создателя Linux, его ник на GitHub torvalds:

curl https://api.github.com/users/torvalds

{
  "login": "torvalds",
  "id": 1024025,
  "name": "Linus Torvalds",
  "company": "Linux Foundation",
  "location": "Portland, OR",
  "public_repos": 8,
  "followers": 230000,
  "created_at": "2011-09-03T15:26:22Z"
}

Снова та же тройка: адрес https://api.github.com/users/torvalds, запрос “дай данные”, ответ — но теперь ответ это структурированные данные в JSON. Прочитайте его как обычный список фактов о человеке:

• login — ник пользователя: torvalds.
• name — полное имя: Linus Torvalds.
• location — город: Portland, OR.
• public_repos — сколько у него публичных репозиториев.
• followers — сколько у него подписчиков.

Каждая строка — это пара “название поля: значение”. Это и есть JSON: текст, но аккуратно разложенный по полочкам, чтобы и человек, и программа понимали, где что лежит. Детально формат JSON мы разберём в модуле 04 — пока достаточно увидеть, что ответ читаемый.

Попробуйте подставить свой ник GitHub (или любой другой) вместо torvalds:

curl https://api.github.com/users/octocat

{
  "login": "octocat",
  "name": "The Octocat",
  "company": "GitHub",
  "location": "San Francisco",
  "public_repos": 8
}

Вы меняете последнюю часть адреса — и просите другой ресурс. Сервер каждый раз отвечает данными именно про того пользователя, которого вы указали. Это в точности “номер квартиры” из прошлого урока: меняете путь — получаете другой ресурс.

Попробуй сам

Теперь вы умеете делать настоящие запросы. Закрепим:

1. Выполните curl https://api.github.com/zen пять раз подряд. Убедитесь, что фразы разные — значит, каждый запрос реально уходит на сервер и возвращается свежий ответ.

2. Запросите данные про трёх разных пользователей GitHub (например, torvalds, octocat и свой ник). Найдите в каждом JSON-ответе поля name, location и public_repos.

3. Попробуйте запросить заведомо несуществующего пользователя:

curl https://api.github.com/users/this-user-does-not-exist-12345

{
  "message": "Not Found",
  "status": "404"
}

Заметьте: даже когда пользователя нет, сервер всё равно отвечает — он сообщает “Not Found” (“не найдено”). Помните урок про ответ? Отказ — это тоже полноценный ответ. Загадочное число 404 — это статус-код, и о том, что означают такие числа, будет отдельный урок в модуле 02.

Что дальше

Вы прошли путь от “что вообще значит слово API” до настоящего запроса к живому серверу. Теперь у вас есть прочная опора: вы понимаете идею (официант, клиент, сервер), форму разговора (адрес, запрос, ответ) и умеете сделать запрос руками через curl.

Дальше курс начинает копать вглубь. В модуле 02 мы разберём HTTP детально: как именно устроен запрос и ответ изнутри, что такое методы (GET, POST и другие), что означают статус-коды вроде 200, 404, 500, и как читать заголовки. Потом — форматы данных, REST-дизайн, аутентификация, и в конце вы соберёте полноценный конвейер забора данных через API на Python.

Но вся эта глубина ложится поверх той простой картинки, которую вы только что прожили руками. Адрес, запрос, ответ — всё остальное лишь уточняет детали.