API (Application Programming Interface) — Module 18.2

How This Lesson Fits the Module & Volume

Module 18.1 gave you three vendor clients: OpenAI, Anthropic, Gemini. An SDK is someone else’s API wrapped in a language. Module 18.2 is about your API—the HTTP contract mobile apps, web UIs, and other services call so they never see vendor keys or vendor JSON.

This opener defines REST-ish HTTP, status codes, versioning, and why AI products still look like request/response (plus streaming later). Next lecture implements it in FastAPI (then Flask). You left Vol. 17’s A1111 port 7860; do not replace it with a naked SDK in the browser.

Learning Objectives

By the end of this lesson, students should be able to:

Define an API as a stable contract (methods, schemas, errors), not “whatever the notebook returned.”
Map HTTP verbs, paths, and status codes to an AI chat/job resource.
Contrast vendor SDK vs your public API vs local WebUI.
Version and document JSON bodies (OpenAPI preview for FastAPI).
Place auth, idempotency, and rate limits as API concerns before Docker/K8s.
Explain why long LLM calls need jobs, webhooks, or streaming—not only sync POST.

Definition

An Application Programming Interface (API) is a documented contract that lets one program invoke another: operations, inputs, outputs, and error modes. In this module it almost always means HTTP + JSON (REST-ish resources, sometimes RPC-style POST /v1/chat). An SDK is a client library for an API. Your product API is what you guarantee; OpenAI/Anthropic/Gemini APIs are dependencies behind it.

Three Layers Students Confuse

Layer	Example	Who consumes it
Local studio HTTP	A1111 `/sdapi/v1/txt2img`	You on localhost—not customers
Vendor API + SDK	`client.chat.completions.create`	Your backend only
Product API	`POST /v1/chat` with your JWT	Web, mobile, partners

HTTP Building Blocks for AI Backends

Piece	Typical AI use
`GET`	Fetch job status, usage, model list (safe, cacheable)
`POST`	Create a chat turn, embedding batch, or async job
`DELETE`	Revoke API keys, cancel a run
200 / 201	Success; 201 if you created a job resource
400 / 401 / 403 / 409 / 429	Bad schema, unauthenticated, forbidden, conflict, rate limit
504 / 499	Upstream LLM timeout / client hung up mid-stream

A Tiny Product Contract (then FastAPI)

Design the JSON first. Frameworks come next. Idempotency keys matter when the client retries a paid completion.

# Product API sketch (not a framework yet)
# POST /v1/chat
# Headers: Authorization: Bearer <user_jwt>
#          Idempotency-Key: 8f3c...   (optional, for paid retries)
{
  "provider": "openai",          # or anthropic | gemini | auto
  "model": "gpt-4.1-mini",       # optional override; default from config
  "messages": [
    {"role": "user", "content": "Summarize this ticket."}
  ],
  "stream": false
}

# 200 response DTO — never leak vendor SDK objects
{
  "id": "cmpl_01H...",
  "text": "The ticket is a billing mismatch on invoice 4412.",
  "usage": {"input_tokens": 128, "output_tokens": 42},
  "provider": "openai",
  "model": "gpt-4.1-mini"
}

# Async alternative for long gens / stills:
# POST /v1/jobs  -> 201 { "id": "job_...", "status": "queued" }
# GET  /v1/jobs/job_...  -> status + result (Celery + Redis later)

API Styles You Will Meet

REST-ish JSON

Resources: chats, jobs, keys
Easy to document (OpenAPI)
Default for this curriculum

RPC / GraphQL

Single /graphql or gRPC
Useful internally; extra cache/auth work
Do not start here for an LLM wrapper

Streaming transports

SSE / chunked
WebSockets
Same resource, different delivery

A good product API

Versioned (/v1), documented, stable errors
Authn/z on every mutating route
Hides provider SKUs unless you intend multi-model UX

A notebook pretending to be an API

No schema; 200 with a stack trace
Vendor key in query string
Sync 120s LLM call with no timeout story

Related Lectures

Lecture	Role
Gemini SDK	Last vendor client; now wrap all three
FastAPI	Implement this contract in Python
Authentication	Who may call `/v1/chat`
Celery	Async jobs when POST cannot wait
A1111	Local sdapi is not your public API

Common Misconception

“The OpenAI SDK is our API.” It is a dependency. Customers should call you. Second: REST is not “only GET/POST on nouns”—many AI APIs are RPC-style POSTs with resourceful jobs beside them; that is fine if documented. Third: returning 200 with {"error": "..."} breaks every client’s retry logic. Fourth: GraphQL will not save you from token cost or GPU queueing.

Knowledge Check

Short Answer: What is the difference between an SDK and an API? Answer: An API is the contract; an SDK is a language client for that (or another) API.
True/False: Your web app should call OpenAI directly with the org key. Answer: False—call your product API; backend holds vendor keys.
Multiple Choice: HTTP 429 usually means: (a) rate limited, (b) model hallucinated, (c) CUDA OOM. Answer: (a).
Short Answer: Why include an Idempotency-Key on paid POSTs? Answer: So retries do not double-bill or double-generate.
True/False: A1111 /sdapi is a fine public multi-tenant API as-is. Answer: False.
Multiple Choice: 201 is most appropriate when: (a) you created a job resource, (b) you trained k-means, (c) PNG Info failed. Answer: (a).
Short Answer: Name one field a chat response DTO should include besides text. Answer: Any of: id, usage tokens, provider, model, finish/stop reason.
True/False: Streaming is a different resource from chat; it cannot share the same route with a flag. Answer: False—often same POST with stream=true (SSE).
Multiple Choice: Next lecture implements this contract with: (a) FastAPI, (b) t-SNE, (c) ControlNet. Answer: (a).
Short Answer: Who just finished as the previous module’s last SDK? Answer: Gemini SDK.

Key Takeaways

API = contract; SDK = client; product API ≠ vendor API.
Design JSON + status codes + versioning before picking Flask vs FastAPI.
Hide keys; meter usage; plan timeouts and async jobs.
Local WebUI HTTP is not shipping.
Next: FastAPI.

Trainer’s Guide

Lab: On paper only, specify /v1/chat and /v1/jobs (headers, bodies, 4 error codes). No framework yet. Peer-review whether a mobile intern could implement the client.

Whiteboard: Browser → your API → OpenAI/Anthropic/Gemini. Cross out any arrow from browser to vendor.

Recap: Your HTTP contract is the product. Implement it next with FastAPI.