SDK vs REST API: чем они отличаются и что выбрать

В предыдущих уроках мы работали с REST API напрямую через requests.get() и requests.post(). Но у многих сервисов есть готовые SDK — и для Gemini, и для AWS, и для Stripe. Разберёмся что это такое и когда использовать каждый подход.

Что такое SDK

SDK (Software Development Kit) — это библиотека которую сервис сам написал для разработчиков. SDK — обёртка над REST API: внутри те же HTTP-запросы, но ты работаешь с удобными классами и методами.

# Без SDK — вручную через requests:
import requests
response = requests.post(
    "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent",
    params={"key": API_KEY},
    json={
        "contents": [{"role": "user", "parts": [{"text": "Привет!"}]}]
    }
)
text = response.json()["candidates"][0]["content"]["parts"][0]["text"]

# Через SDK — то же самое, но чище:
import google.generativeai as genai
genai.configure(api_key=API_KEY)
model = genai.GenerativeModel("gemini-1.5-flash")
response = model.generate_content("Привет!")
text = response.text

Оба варианта делают одно и то же — второй просто читаемее.

Что SDK делает за тебя

• Сериализация — преобразует Python-объекты в нужный JSON формат и обратно
• Авторизация — подставляет токен в правильное место
• Retry — автоматически повторяет запрос при временных ошибках
• Валидация — проверяет параметры до отправки запроса
• Типизация — IDE подсказывает доступные методы и параметры

Когда использовать SDK

Используй SDK когда:
- Сервис официально поддерживает SDK для твоего языка
- SDK активно развивается (смотри дату последнего коммита в GitHub)
- Тебе важна скорость разработки
- API сложный (много типов запросов, вложенные структуры)

Используй raw requests когда:
- SDK нет или он устаревший
- Нужен максимальный контроль над запросом
- Учишься — важно понять как API работает «под капотом»
- Минималистичный скрипт без лишних зависимостей

Зависимости: цена SDK

SDK — дополнительная зависимость. Пакет google-generativeai тянет за собой несколько десятков других пакетов. Это нормально для приложения, но много для маленького скрипта.

pip install google-generativeai  # ~50 MB зависимостей
pip install requests              # ~3 MB

SDK не скрывает API — он его отражает

Понимание REST API помогает разобраться в SDK. Если знаешь что Gemini принимает contents как список объектов с role и parts — легко понять почему SDK делает именно так. И наоборот — SDK показывает как правильно структурировать запросы.

Итог

SDK и REST API — не противоположности, а уровни абстракции. В реальных проектах обычно берут SDK если он есть. В этом курсе мы использовали raw requests в уроках 1–4 чтобы понять механику. В уроке 5 используем Gemini SDK — потому что он официальный, хорошо документирован и экономит время.