SDK vs REST API: What's the Difference and Which Should You Use

In previous lessons we worked with REST APIs directly via requests.get() and requests.post(). But many services ship their own SDK — Gemini, AWS, and Stripe all do. Let’s break down what an SDK is and when to use each approach.

What Is an SDK

An SDK (Software Development Kit) is a library the service itself built for developers. An SDK is a wrapper around the REST API: under the hood it’s the same HTTP requests, but you work with convenient classes and methods instead.

# Without SDK — manually via 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"]

# Via SDK — same thing, but cleaner:
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

Both approaches do exactly the same thing — the second one is just more readable.

What an SDK Does for You

• Serialization — converts Python objects to the correct JSON format and back
• Authentication — inserts the token in the right place automatically
• Retry logic — automatically retries requests on transient errors
• Validation — checks parameters before the request is sent
• Type hints — your IDE suggests available methods and parameters

When to Use an SDK

Use an SDK when:
- The service officially supports an SDK for your language
- The SDK is actively maintained (check the date of the latest commit on GitHub)
- Development speed matters
- The API is complex (many request types, deeply nested structures)

Use raw requests when:
- There’s no SDK, or the existing one is outdated
- You need full control over the request
- You’re learning — it’s important to understand how the API works under the hood
- You’re writing a minimal script with no extra dependencies

Dependencies: The Cost of an SDK

An SDK is an additional dependency. The google-generativeai package pulls in dozens of other packages. That’s fine for an application, but a lot for a small script.

pip install google-generativeai  # ~50 MB of dependencies
pip install requests              # ~3 MB

An SDK Doesn’t Hide the API — It Reflects It

Understanding the REST API helps you understand the SDK. If you know that Gemini expects contents as a list of objects with role and parts, it’s easy to see why the SDK is structured the way it is. And the reverse is also true — the SDK shows you how to structure requests correctly.

Summary

SDK and REST API aren’t opposites — they’re different levels of abstraction. In real projects, you’ll typically reach for the SDK if one exists. In this course we used raw requests in lessons 1–4 to understand the mechanics. In lesson 5 we use the Gemini SDK — because it’s official, well-documented, and saves time.