API

Что такое API?

API (Application Programming Interface) — это способ, которым одна программа общается с другой.

Чаще всего в дата-инженерии под API имеют в виду HTTP API: мы отправляем запрос и получаем ответ в формате JSON, CSV, XML или другом формате.

Пример открытого API

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

from datetime import date, timedelta
 
import pandas as pd
import requests
 
today = date.today()
start_date = (today - timedelta(days=7)).isoformat()
end_date = today.isoformat()
 
response = requests.get(
    "https://api.open-meteo.com/v1/forecast",
    params={
        "latitude": 55.7522,
        "longitude": 37.6156,
        "hourly": ["temperature_2m", "rain"],
        "start_date": start_date,
        "end_date": end_date,
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()
 
hourly = data.get("hourly", {})
df = pd.DataFrame(
    {
        "time": hourly.get("time", []),
        "temperature_2m": hourly.get("temperature_2m", []),
        "rain": hourly.get("rain", []),
    }
)
 
df.to_csv("weather_forecast.csv", index=False, encoding="utf-8-sig")

Что здесь происходит:

requests.get(...) отправляет HTTP-запрос;
params формирует query-параметры в URL;
raise_for_status() падает на ошибках 4xx и 5xx;
response.json() превращает ответ в Python-словарь;
pandas.DataFrame(...) удобно собирает данные в таблицу.
df.to_csv(...) сохраняет результат в CSV-файл, который потом можно открыть в Excel, pandas или загрузить дальше в ETL.

Что такое пагинация?

Пагинация — это способ отдавать данные не одним огромным ответом, а частями, по страницам.

Это нужно, когда:

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

Обычно API возвращает:

сами данные текущей страницы;
номер следующей страницы;
общее количество записей или страниц;
флаг, что данные закончились.

Пример пагинации

Представь, что у тебя 10 000 строк, а API отдаёт только по 100 строк за раз.

Тогда запросы выглядят так:

page = 1
limit = 100
 
while True:
    response = requests.get(
        "https://example.com/api/v1/items",
        params={
            "page": page,
            "limit": limit,
        },
        timeout=60,
    )
    response.raise_for_status()
    data = response.json()
 
    items = data.get("results", [])
    if not items:
        break
 
    # обрабатываем текущую страницу
    page += 1

То есть пагинация помогает забирать данные порциями, а не пытаться вытащить всё одним запросом.

Какие бывают API?

На практике чаще всего встречаются такие варианты:

Тип API	Что это значит	Пример
Открытый / публичный	Доступен всем без отдельного согласования	Open-Meteo, публичные справочники
Закрытый / приватный	Доступен только авторизованным клиентам	Внутренний API компании
Партнёрский	Доступен по договорённости между компаниями	API платёжных систем, рекламных кабинетов
Внутренний	Используется только между сервисами компании	Микросервисы внутри одного продукта

Закрытые API и токены

У закрытого API обычно есть авторизация. Самые частые варианты:

API key;
Bearer token;
OAuth access token;
иногда Basic Auth.

Чаще всего токен передают в заголовке:

headers = {
    "Authorization": f"Bearer {token}",
}
 
response = requests.get(
    "https://example.com/api/v1/data",
    headers=headers,
    timeout=60,
)

Иногда токен передают как X-API-Key, а иногда кладут в query-параметр, но заголовок безопаснее и привычнее.

Лимиты в API

У многих API есть ограничения:

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

Если лимит превышен, API часто отвечает кодом 429 Too Many Requests.

Что обычно делают:

читают документацию по rate limit;
используют пагинацию;
ставят sleep или backoff;
повторяют запросы с паузой;
кешируют данные, если это допустимо.

Синхронные и асинхронные API

Синхронные API

Это самый простой вариант: ты отправляешь запрос и ждёшь ответ сразу.

Подходит для:

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

Асинхронные API

Тут запрос не выполняется мгновенно.

Обычно схема такая:

Ты отправляешь запрос на создание задачи;
API возвращает job_id или task_id;
Потом ты либо опрашиваешь статус, либо получаешь webhook;
Когда задача готова, забираешь результат.

Это удобно, когда операция долгая: экспорт отчёта, генерация файла, тяжёлый расчёт.

Что такое gRPC?

gRPC — это не просто "ещё один API", а способ делать API для общения сервисов между собой.

Если очень просто:

REST обычно передаёт JSON по HTTP;
gRPC использует HTTP/2 и Protocol Buffers;
сообщения короче и быстрее сериализуются;
можно делать не только обычные запросы, но и стриминг.

gRPC особенно удобен для:

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

Для публичных API gRPC используется реже, а для внутренней сервисной связки — очень часто.

Коротко

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

Что такое Virtual Machine Теория по HDFS