HTTP, REST APIs & Web Fundamentals

HTTP = HyperText Transfer Protocol

Every time you open a website, call an API, or send a prompt to ChatGPT, you're using HTTP. It's the standard protocol (set of rules) for communication on the internet.

Think of HTTP like India Post. You write a letter (request), put it in an envelope with an address (URL), and send it. The recipient processes it and sends back a reply (response). HTTP defines the format of these "letters" so everyone understands each other.

The Request-Response Cycle:

CLIENT (your code)                    SERVER (OpenAI, etc.)
     |                                      |
     |--- HTTP Request (POST /v1/chat) ---->|
     |    Headers: Authorization, Content-Type
     |    Body: {"messages": [...]}          |
     |                                      |
     |<-- HTTP Response (200 OK) -----------|
     |    Headers: Content-Type: application/json
     |    Body: {"choices": [...]}           |

HTTP Methods (The Verbs):

• GET - Read/fetch data (like browsing a menu)
• POST - Create/send data (like placing an order). Used for ALL LLM API calls!
• PUT - Update/replace data (like changing your entire order)
• PATCH - Partially update data (like changing just the drink in your order)
• DELETE - Remove data (like cancelling an order)

HTTP Status Codes (The Reply Codes):

• 200 - OK (everything worked!)
• 201 - Created (resource successfully created)
• 400 - Bad Request (you sent something wrong)
• 401 - Unauthorized (invalid API key)
• 403 - Forbidden (you don't have access)
• 404 - Not Found (wrong URL)
• 429 - Too Many Requests (rate limited! Very common with LLM APIs)
• 500 - Internal Server Error (server crashed)

What Makes an API "RESTful":

REST is a set of design principles for APIs. Think of it like grammar rules for API URLs. Just like Hindi has grammar rules that make sentences understandable, REST has rules that make APIs predictable and consistent.

• Resource-based URLs: /users, /products, /messages (nouns, not verbs)
• HTTP methods as actions: GET /users (list), POST /users (create), GET /users/123 (get one)
• Stateless: Each request contains all info needed. Server doesn't remember previous requests.
• JSON for data: Request and response bodies are typically JSON.

REST API Design Pattern:

GET    /api/users           → List all users
POST   /api/users           → Create a new user
GET    /api/users/123       → Get user with ID 123
PUT    /api/users/123       → Update user 123
DELETE /api/users/123       → Delete user 123

AI API Examples:
POST   /v1/chat/completions → OpenAI chat (send prompt, get response)
POST   /v1/messages         → Claude API (send messages, get response)
POST   /v1/embeddings       → Get text embeddings

Headers - The Metadata:

HTTP headers are like the "from" and "to" fields on an envelope. Important headers you'll use daily:

• Authorization: Bearer sk-xxx - Your API key (like your ID card)
• Content-Type: application/json - "I'm sending JSON data"
• Accept: application/json - "I want JSON back"

Using requests Library:

import requests

# Simple GET request
response = requests.get("https://api.example.com/users")
data = response.json()  # Parse JSON response

# POST request to OpenAI
response = requests.post(
    "https://api.openai.com/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-your-api-key",
        "Content-Type": "application/json"
    },
    json={
        "model": "gpt-4",
        "messages": [{"role": "user", "content": "Hello!"}]
    }
)

if response.status_code == 200:
    result = response.json()
    print(result["choices"][0]["message"]["content"])
elif response.status_code == 429:
    print("Rate limited! Wait and retry.")
else:
    print(f"Error: {response.status_code}")

Using curl (Command Line):

# Test any API from terminal
curl -X POST https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"Hi"}]}'

curl is the fastest way to test APIs. Every AI engineer uses it for quick debugging.

Mistake 1: Hardcoding API Keys

NEVER put API keys directly in code. Use environment variables or .env files. If your code goes to GitHub, your key leaks and someone else uses your OpenAI credits!

Mistake 2: Not Handling Errors

APIs fail. Networks go down. Servers crash. ALWAYS check the status code and handle errors. Implement retry logic with exponential backoff for transient errors (429, 500, 503).

Mistake 3: No Timeout

Without a timeout, your code can hang forever if the server doesn't respond. Always set timeouts!

# Always set timeout!
response = requests.post(url, json=data, timeout=30)  # 30 seconds max

Best Practices:

• Store API keys in environment variables
• Always set request timeouts
• Implement retry logic with exponential backoff
• Log request/response for debugging
• Use API client libraries when available (openai, anthropic SDKs)

Q1: What's the difference between GET and POST?

Answer: GET retrieves data and has no body (parameters go in URL). POST sends data in the request body (used for creating resources and LLM API calls). GET is idempotent (calling it multiple times has same result), POST is not.

Q2: What does stateless mean in REST?

Answer: Each request contains all information needed to process it. The server doesn't store any client state between requests. This is why you send your API key with EVERY request to OpenAI - the server doesn't remember who you are from the previous request.

Q3: How do you handle API rate limiting?

Answer: Implement exponential backoff: when you get 429, wait 1s, retry. If 429 again, wait 2s, then 4s, then 8s. Cap at a maximum wait time. Use the Retry-After header if provided. For batch processing, use semaphores to limit concurrent requests.