SDK and REST API: What's the Difference and Which Should You Choose?

In earlier lessons, you called APIs directly with requests: you supplied the URL, HTTP method, headers, and parameters yourself. Lesson 5 uses the official Gemini SDK. This is not a different API; it is a more convenient way to use that API from Python.

The short answer

• A REST API defines how to communicate with a service over HTTP: endpoints, methods, headers, request bodies, and response formats.
• An SDK is a language-specific library that exposes those rules through classes and methods.

An SDK usually sends HTTP requests internally. It does not replace the server API or remove status codes, quotas, and network failures.

One request, two approaches

You can call the Gemini Interactions API directly:

import requests

response = requests.post(
    "https://generativelanguage.googleapis.com/v1beta/interactions",
    headers={
        "x-goog-api-key": API_KEY,
        "Content-Type": "application/json",
    },
    json={
        "model": "gemini-3.6-flash",
        "input": "Explain REST APIs in two sentences",
        "store": False,
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()

The official google-genai package expresses the same operation more concisely:

from google import genai

with genai.Client(api_key=API_KEY) as client:
    interaction = client.interactions.create(
        model="gemini-3.6-flash",
        input="Explain REST APIs in two sentences",
        store=False,
    )

print(interaction.output_text)

In the second version, the SDK knows the endpoint, builds the request body, and turns the response into a Python object. The operation itself is still the same.

What an SDK actually provides

An official SDK commonly provides:

• named methods instead of manually assembled URLs;
• serialization between Python objects and JSON;
• response models and type hints for your IDE;
• convenience properties such as interaction.output_text;
• support for API features such as streaming, structured output, and interaction continuation;
• one place to configure the client, timeout, and other HTTP options.

Do not assume the SDK validates everything for you. Your program still needs to reject empty prompts, validate its own arguments, and assess the meaning of model output. Retry behavior also depends on the SDK and its configuration, so verify it in the documentation.

When an SDK is the better choice

Choose an official SDK when:

• it is actively maintained for your language;
• the API has complex structures, streaming, or multiple modes;
• type hints, autocomplete, and development speed matter;
• the service documentation uses current examples from that SDK.

For Gemini, use google-genai. The old google-generativeai package, the google.generativeai import, and genai.configure() are not appropriate for a new project.

When direct HTTP is the better choice

Choose requests or httpx when:

• no official SDK exists or it lags behind the API;
• you need an endpoint the SDK does not support yet;
• you need complete control over URLs, headers, and request bodies;
• the script is small and an extra dependency is unnecessary;
• you are learning HTTP and want every part of the request to remain visible.

Direct HTTP is not an inferior or obsolete option. Sometimes it is the simplest and most transparent one.

How to evaluate an SDK

Do not install a package because its name merely looks official. Check that:

1. The service’s official documentation links to it.
2. It supports your language and the API feature you need.
3. Current examples use the same import and methods.
4. Your requirements.txt pins a sensible version range.
5. You understand its exceptions and how it configures timeout or retry behavior.

The lesson project uses:

google-genai>=2.17,<3

Install dependencies from the file:

python -m pip install -r requirements.txt

Summary

A REST API is the service contract; an SDK is a convenient client for that contract. Understand the request first, then choose the most reliable way to send it.

Whichever approach you choose, validate input, keep the key outside the code, centralize network access, and handle expected failures clearly. For Gemini, the current official google-genai SDK is the right choice. For a small or unsupported endpoint, direct HTTP may be better.