ОТ ПЕРВОГО ЗАПРОСА ДО СВОЕГО ПРОЕКТА

ПОНЯТЬ API.
СОЗДАТЬ СВОЁ.

Как программы общаются друг с другом? Разберись на примере супергероев — от одного GET-запроса до целой игры на Python.

Начать изучение ↘Сразу к практике ↗

Для начинающихПолный Python-код12 заданий

первый-запрос.httpПРИМЕР

// Получаем данные для своей игры

GET /api/id/332.json

↓Сервер находит героя

200 OKapplication/json

{
  "id": 332,
  "powerstats": {
    "strength": 100
  }
}

Сокращённый пример JSON-ответа

Данные из API.
Правила игры — твои.

01 / ОСНОВЫ

Программам тоже нужен
общий язык.

API — это правила, по которым одна программа обращается к другой. Они описывают доступные действия, нужные данные и формат результата. Тебе не нужно знать внутреннее устройство сервиса, чтобы пользоваться его возможностями.

Представь меню в кафе

В меню перечислено, что можно заказать. Ты передаёшь заказ, кухня его готовит и возвращает результат. API — такое «меню» для программы. Здесь мы изучаем HTTP API: общение по сети через запросы и ответы. Не каждый API работает через интернет.

Один клик. Пять шагов.

01ДействиеОткрываешь досье
02ЗапросGET + ID героя
03ОтветСтатус + JSON
04ОбработкаКод читает поля
05ИнтерфейсВидишь карточку

Где это работает в реальных проектах

01 / МАГАЗИН

Каталог → заказ

Сайт получает товары и остатки через GET. Когда покупатель оформляет заказ, POST передаёт выбранные товары серверу.

02 / ПОГОДА

Город → прогноз

Приложение отправляет координаты, получает температуру и вероятность дождя, а затем рисует понятный прогноз.

03 / КАРТЫ И ДОСТАВКА

Адрес → маршрут

Сервис запрашивает маршрут, расстояние и время в пути. Приложение доставки показывает движение заказа.

04 / TELEGRAM-БОТЫ

Команда → ответ

Программа получает сообщения через Bot API, обрабатывает команду пользователя и обращается к API для отправки ответа.

05 / НАША ИГРА

Герои из API. Бой из кода.

Superhero API отдаёт имена, изображения и характеристики. Выбор команд, здоровье, урон и победу рассчитывает сама игра. API не проводит бой за нас.

ПРОГРАММА НА PYTHON

Python → Superhero API

requests.get() обращается к внешнему источнику напрямую. response.json() возвращает словарь героя или список героев.

{"id": 332, "powerstats": {"strength": 100}}

САЙТ «АРЕНА»

Браузер → PHP → API

JavaScript обращается к api.php. PHP получает сведения из внешнего API или кеша и добавляет служебный объект meta.

{
  "data": {"id": 332, "powerstats": {"strength": 100}},
  "meta": {"cache": true, "stale": false, "source": "…"}
}

JSON выше сокращён для объяснения структуры. В практике выводится настоящий ответ. cache показывает чтение из PHP-кеша; stale — использование устаревших данных при недоступности источника.

Мини-словарь: 10 терминов без сложных слов +

Клиент: Программа, которая отправляет запрос: например, браузер или Python-скрипт.
Сервер: Программа, которая принимает запрос, выполняет работу и возвращает ответ.
Ресурс: То, с чем работает API: герой, товар, заказ или коллекция записей.
Endpoint: Адрес обращения к API. Метод и путь вместе определяют операцию.
HTTP: Протокол обмена запросами и ответами между клиентом и сервером.
JSON: Текстовый формат данных: объекты, массивы, строки, числа, true, false и null. Это не Python-код.
REST: Архитектурный стиль API с ресурсами и единым интерфейсом. Наличие JSON само по себе не делает API REST.
CRUD: Create, Read, Update, Delete: создание, чтение, изменение и удаление данных.
Кеш: Сохранённый ответ, который можно использовать повторно, не запрашивая источник каждый раз.
Токен: Данные для подтверждения доступа. Секретные токены нельзя публиковать в коде сайта. Для этого Superhero API ключ не нужен.

02 / HTTP

Один адрес.
Разные действия.

URL отвечает на вопрос «где?», а HTTP-метод — «что сделать?». Ответ содержит статус, заголовки и, если это предусмотрено, тело с данными.

анатомия-запроса.http

GET api.php?resource=hero&id=332

Accept: application/json

GET — метод · api.php — адрес · после ? — параметры · Accept — желаемый формат ответа

Заголовки — сведения о сообщении. Например, Content-Type: application/json говорит, что тело содержит JSON. Accept описывает желаемый формат ответа.

Тело — передаваемые данные. POST, PUT и PATCH часто отправляют JSON. Параметры после ? уточняют запрос и отделяются друг от друга символом &.

Метод / действие	Что происходит	Пример пути	Тело запроса	Типичный успех
GETПолучить	Читает данные, не изменяя ресурс.	`/heroes/1`	Нет	200 + JSON
POSTСоздать / выполнить	Передаёт данные для создания ресурса или выполнения операции.	`/heroes`	Обычно JSON	201 + новый ресурс
PUTЗаменить целиком	Передаёт полное новое представление ресурса по известному адресу.	`/heroes/1`	Полный объект	200 или 204
PATCHИзменить частично	Передаёт только нужные изменения. Формат зависит от конкретного API.	`/heroes/1`	Изменения	200 или 204
DELETEУдалить	Удаляет указанный ресурс.	`/heroes/1`	Обычно нет	204 без тела
HEADПрочитать заголовки	Как GET, но ответ не содержит тела: можно узнать тип содержимого.	`/heroes/1`	Нет	200, без тела
OPTIONSУзнать возможности	Описывает доступные операции; Allow может содержать список методов.	`/heroes/1`	Нет	200 или 204

Пути в таблице — условные примеры. Конкретные статусы и формат тела определяет документация API. Внешний каталог героев и PHP API сайта используются для чтения; операции изменения доступны в нашем симуляторе.

PUT /heroes/1

Новая версия целиком

В тренажёре обязательно передать все изменяемые поля. ID берётся из адреса.

{
  "name": "Страж",
  "role": "Защитник",
  "hp": 220
}

Имя, роль и здоровье заменены.

PATCH /heroes/1

Только нужная часть

Меняем одно поле, остальные оставляем как были. В тренажёре используем обычный JSON-объект.

{
  "hp": 180
}

Изменилось только здоровье.

Что будет, если повторить запрос?

GET не должен изменять ресурс. Повтор одинакового PUT или DELETE имеет тот же итоговый эффект, хотя ответы могут различаться: после удаления второй DELETE может вернуть 404. POST может создать ещё одну запись. Для PATCH поведение зависит от операции: «установить HP в 180» и «прибавить 10 HP» ведут себя по-разному.

Статус — первая подсказка

2xx / УСПЕХ

200 OK: Запрос выполнен, обычно есть данные.
201 Created: Создан новый ресурс.
204 No Content: Выполнено, тело ответа отсутствует.

4xx / ПРОВЕРЬ ЗАПРОС

400 Bad Request: Некорректные параметры или тело.
401 / 403: Нужна авторизация / доступ запрещён.
404 / 405: Ресурс не найден / метод запрещён.
429 Too Many Requests: Слишком много запросов; нужен перерыв.

5xx / ПРОБЛЕМА СЕРВЕРА

500 Internal Server Error: Внутренняя ошибка сервера.
503 Service Unavailable: Сервис временно недоступен.

На этом сайте 503 означает: источник недоступен и подходящего сохранённого ответа нет.

Нет сети — это не HTTP 500. Если ответ сервера не получен, HTTP-статуса может вообще не быть. Отдельно обрабатывай сетевые ошибки, тайм-ауты и случай, когда сервер вместо JSON вернул HTML.

Подробнее: HTTP-методы в MDN ↗

03 / PYTHON

Теперь посмотрим,
как это написано.

Сначала — короткий запрос, который можно запустить отдельно. Затем — вся программа Superhero Draft с комментариями и разбором по шагам.

first_request.py

import requests  # Сначала: python -m pip install requests

url = 'https://akabab.github.io/superhero-api/api/id/332.json'
try:
    response = requests.get(url, timeout=15)  # Отправляем GET.
    response.raise_for_status()             # Проверяем HTTP-ошибки.
    hero = response.json()                  # JSON-объект → словарь.
    print(hero['name'])                      # Читаем поле по ключу.
    print(hero['powerstats']['strength'])    # Вложенный словарь.
except requests.exceptions.JSONDecodeError:
    print('Сервер вернул не JSON.')
except requests.RequestException as error:
    print('Не удалось получить героя:', error)

Подготовь Python на своём компьютере

Нужен Python 3.10 или новее. Скачай полный файл ниже, открой терминал в его папке и выполни команды. На macOS и Linux команда может называться python3.

python --version
python -m pip install requests Pillow
python -m tkinter
python hero_commented.py

python -m tkinter должен открыть тестовое окно. Закрой его перед запуском игры. Если модуль отсутствует, установи поддержку Tcl/Tk для своей версии Python; Tkinter не устанавливается командой pip install tkinter.

Игра откроется отдельным окном. На этой странице мы читаем код и выполняем API-запросы — графическое приложение Tkinter работает локально.

ШАГ РАЗБОРА

hero_commented.py

Для пошагового просмотра включите JavaScript. Полный комментированный исходник доступен по ссылке «Скачать .py» выше.

Заметь границу ответственности.

name, powerstats, images и connections приходят из API. Роли, HP, урон, лечение и бонусы — правила программы. Во время боя JSON-запросы для расчёта ходов не нужны.

Документация: Requests ↗ · Tkinter ↗

04 / ПРАКТИКА

Твой запрос.
Твой результат.

0 / 12ЗАДАНИЙ ВЫПОЛНЕНО

Первые три задания обращаются к настоящему API сайта. Остальные работают в учебном симуляторе в твоём браузере. Изменения живут до перезагрузки страницы.

При выборе задания симулятор начинает с двух записей: Сокол (#1, Стратег, 120 HP) и Титан (#2, Защитник, 240 HP). Можно проходить задания в любом порядке.

Нужна подсказка?

Показать решение

02 / ОТВЕТОЖИДАНИЕ

Нажми «Выполнить запрос», чтобы увидеть ответ.

Заголовки ответа

Пока нет ответа.

ТЕЛО ОТВЕТА

// Здесь появится ответ

Состояние учебных данных после запроса

ПОНЯТЬ API.СОЗДАТЬ СВОЁ.

Программам тоже нуженобщий язык.