Что такое API и как с ним работать: запрос, ответ, пример

API — это описанный способ, которым одна программа просит другую отдать данные или выполнить действие: вы отправляете запрос в оговорённой форме и получаете ответ в оговорённой форме. Статья для тех, кто уже пишет простые программы на Python. Вы разберёте, из чего состоят запрос и ответ, и сами запросите у Банка России официальные курсы валют.

Определения взяты из глоссария MDN, коды состояния — из справочника MDN и RFC 9110, описание интерфейса — со страницы Банка России. Код проверен запуском на Python 3.13. Данные на октябрь 2026 года.

Что такое API простыми словами

Глоссарий MDN определяет API (Application Programming Interface, программный интерфейс приложения) как набор функций и правил, позволяющих программным компонентам взаимодействовать. Привычный образ — меню в кафе. Вы не заходите на кухню, а заказываете блюдо по меню, и вам приносят результат. Меню — это интерфейс: оно описывает, что можно попросить и в какой форме.

В вебе чаще всего говорят о веб-API: вы обращаетесь по адресу в интернете и получаете данные в формате XML или JSON. Тот же принцип работает внутри компьютера: функции библиотеки Python или вызовы операционной системы — тоже API.

Из чего состоит обмен

Веб-API работает по протоколу HTTP. Запрос и ответ строятся по одной схеме, которую описывает RFC 9110.

По MDN, метод GET запрашивает представление ресурса и может только получать данные, а POST отправляет данные на определённый ресурс. Ключ или параметры могут передаваться в заголовках или в адресе — как именно, сказано в документации сервиса.

Первый запрос на Python

Возьмём открытый интерфейс Банка России. На странице «Получение данных, используя XML» написано: запрос с параметром date_req в формате «день/месяц/год» возвращает котировки на заданный день, а без параметра — на последнюю зарегистрированную дату. Наш запрос выполнился без ключа и регистрации.

Нам хватит двух модулей стандартной библиотеки: urllib.request отправит запрос, xml.etree.ElementTree разберёт ответ.

import urllib.request
import xml.etree.ElementTree as ET

адрес = "https://www.cbr.ru/scripts/XML_daily.asp?date_req=02/10/2026"

with urllib.request.urlopen(адрес, timeout=30) as ответ:
    print("Код состояния:", ответ.status)
    print("Тип содержимого:", ответ.headers["Content-Type"])
    данные = ответ.read()

корень = ET.fromstring(данные)
print("Дата курсов:", корень.attrib["Date"])

for валюта in корень.findall("Valute"):
    код = валюта.find("CharCode").text
    if код in ("USD", "EUR", "CNY"):
        номинал = валюта.find("Nominal").text
        курс = валюта.find("Value").text
        имя = валюта.find("Name").text
        print(f"{номинал} {код} ({имя}) = {курс} руб.")

Вывод при запуске на Python 3.13 (запрос выполнен 8 октября 2026 года):

Код состояния: 200
Тип содержимого: application/xml; charset=windows-1251
Дата курсов: 02.10.2026
1 USD (Доллар США) = 83,2454 руб.
1 EUR (Евро) = 94,5252 руб.
1 CNY (Юань) = 12,4028 руб.

Что здесь происходит. Строка с адресом — это эндпоинт и параметр. Функция urlopen отправляет GET-запрос и возвращает ответ, у которого есть код состояния и заголовки. Метод read отдаёт тело как байты, а ET.fromstring превращает их в дерево элементов. Дальше мы ищем элементы Valute и достаём из них код валюты, номинал и курс. Курс приходит текстом с запятой, как принято в России, поэтому для расчётов его нужно заменить на точку и преобразовать в число.

Коды состояния

MDN делит коды на пять классов: 1xx — информационные, 2xx — успешные, 3xx — перенаправление, 4xx — ошибки клиента, 5xx — ошибки сервера. Все они определены в RFC 9110.

Если сервер вернул код 4xx или 5xx, urlopen в Python вызывает исключение urllib.error.HTTPError. Его нужно перехватывать, а не оставлять программе упасть.

Формат ответа: XML и JSON

Банк России отдаёт XML, но чаще веб-API отдают JSON. Модуль json из стандартной библиотеки превращает JSON-текст в словарь и обратно.

import json

текст = '{"валюта": "USD", "курс": 81.5, "обновлено": "2026-10-02"}'
данные = json.loads(текст)
print(данные["валюта"], данные["курс"])
print(json.dumps(данные, ensure_ascii=False))

USD 81.5
{"валюта": "USD", "курс": 81.5, "обновлено": "2026-10-02"}

Числа в этом тексте придуманы для примера: настоящих курсов здесь нет. Он показывает только устройство разбора.

API-ключ и ограничения

Многие сервисы просят представиться. Для этого выдают ключ — длинную строку, которую вы передаёте вместе с запросом. Через ключ сервис связывает запросы с вашей учётной записью и ограничивает их число. Если лимит превышен, в ответ приходит код 429.

Практичный способ — хранить ключ в переменной окружения и читать её в программе через os.environ. Тогда ключа нет в файле с кодом, и вы не выложите его случайно вместе с программой.

Как читать документацию к API

Документация — главный источник. Порядок такой:

1. Найдите раздел с описанием адресов (эндпоинтов) и методов.
2. Посмотрите, нужен ли ключ и как его передавать.
3. Найдите список параметров и формат даты или числа.
4. Откройте пример запроса и ответа и повторите его.
5. Прочтите раздел об ограничениях: лимиты, допустимая частота, условия использования.

На странице Банка России это видно сразу: приведён пример запроса XML_daily.asp?date_req=…, описан формат даты и сказано, что будет, если параметр не указать.

Условия и ограничения

Версия

Python 3.13, октябрь 2026 — код проверен запуском; курсы в выводе даны на 02.10.2026.

Сеть

Нужен интернет — адрес и формат ответа определяет Банк России и они могут измениться; сверяйтесь со страницей описания.

Формат

XML в кодировке windows-1251 — у других сервисов ответ чаще в JSON; библиотека разбора тогда другая.

Правила

Условия сервиса — у каждого сервиса свои лимиты и условия использования; читайте их до начала работы.

Смысл термина

API в сообщениях об ошибках — «API» в сообщении об ошибке игры или программы — другая тема, чем веб-интерфейс из статьи.

Частые ошибки

• Не проверяют код состояния и разбирают пустой или ошибочный ответ.
• Забывают про кодировку: XML Банка России приходит в windows-1251, а не в UTF-8.
• Хранят ключ в коде и выкладывают его в открытый репозиторий.
• Запрашивают данные в цикле без пауз и получают код 429.
• Принимают курс с запятой за число: перед расчётами запятую заменяют на точку.
• Смешивают понятия: «REST» — стиль, а «API» — любой интерфейс.

Короткий вывод

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