Web APIs & JSON payloads
Learn HTTP requests, endpoints, methods, headers, status codes, and formatting JSON payloads for AI services.
Establish Transport pipe connection
Host client (IDE or AI assistant) connects to the server process over standard output streams.
▶📚 Prerequisites(1)
🎓 Learning objectives
- •Grasp HTTP methods: GET, POST, PUT, DELETE
- •Format and send valid JSON API payloads
- •Handle API status codes (200 OK, 401 Unauthorized, 429 Rate Limited)
What is it?
[AI Engineering Prerequisite] An API (Application Programming Interface) is a set of rules allowing different software applications to communicate with each other — typically over HTTP, using request/response messages formatted as JSON. When you call an LLM provider's API (OpenAI, Anthropic), you're sending a JSON request (your prompt and settings) and receiving a JSON response (the generated text and metadata). Understanding APIs is the foundation for every AI Engineering skill that involves calling a model, a vector database, or any external service programmatically.
Why it exists
To use large models hosted on remote servers (like OpenAI or Anthropic), developers need a standard method to send texts and receive responses.
Problem it solves
Enables building applications without running massive neural models locally on user computers.
Intuition
An API is like a waiter in a restaurant: you look at the menu (endpoint documentation), tell the waiter your order (request), and they bring you the food (response) from the kitchen.
Analogy
Sending an API request is like mailing a package: you write the address (Endpoint URL), stick a stamp (API key), and include a structured order sheet (JSON payload).
Technical explanation
APIs use RESTful endpoints over HTTP. Communication is stateless. Standard request contains headers (Content-Type, Authorization) and a raw string body structured in JSON format.
Architecture
Consists of client-side request builders and server-side request listeners, validation layers, routers, and database connectors.
Workflow
- Create dictionary -> 2. Serialize to JSON string -> 3. Send HTTP POST -> 4. Parse JSON response.
Example
import json payload = {"model": "gpt-4", "messages": [{"role": "user", "content": "hi"}]} json_str = json.dumps(payload) print(json_str) # Output: {"model": "gpt-4", "messages": [{"role": "user", "content": "hi"}]}
Real-world usage
Calling Anthropic API to analyze text inputs inside custom Python scripts.
Trade-offs
Using cloud APIs offers high convenience but exposes user data to third parties, unlike running models local.
Visual explanation
API Request-Response Loop: App Client ──(POST JSON request + API Key)──> API Endpoint URL ──(Process Model)──> returns JSON response
Advantages
- —
Allows accessing powerful remote models instantly
- —
Decouples frontend UI code from heavy backend execution
Disadvantages
- —
Requires active internet connection
- —
Incurs network latency and pay-per-token API costs
Common mistakes
- —
Hardcoding API keys in public code repositories (leads to keys being stolen immediately)
- —
Not handling status code 429 (Rate Limits) leading to application crashes under high user traffic
🎤 Interview questions
Explain how RESTful API statelessness works. How do we securely pass credentials in HTTP requests?
📂 Subtopics
What Is an API: The Restaurant Menu Analogy
An API is a defined way for two pieces of software to talk to each other — like a restaurant menu, it lists exactly what you can ask for and what you'll get back, without you needing to know how the kitchen works.
~10 min
REST API Fundamentals: HTTP Methods, Status Codes and JSON Payloads
REST is the dominant style for web APIs: HTTP methods say what ACTION you want, status codes say what HAPPENED, and JSON is the near-universal format for the actual data exchanged.
~13 min
API Authentication: API Keys, Bearer Tokens and Why They Matter
Authentication proves WHO is calling an API. API keys and Bearer tokens are the two forms you'll see constantly — both are secrets that must never leak, since anyone holding them can act as you.
~11 min
Calling LLM APIs: An OpenAI Example End-to-End, Including Streaming
Putting the whole unit together: authenticate, send a JSON request with your prompt, check the status code, parse the JSON response — and handle the streaming variant that most chat UIs actually use.
~14 min