Lesson 2 — Beginner

The Web: HTTP, REST & JSON

Har AI feature ka aadha hissa bahar ke API se judna hota hai — LLM APIs se lekar internal services tak. Sab kuch HTTP par chalta hai. Is lesson mein request/response cycle, methods aur idempotency, status codes, headers/params/bodies, JSON handling, REST endpoint design, authentication basics aur curl se API inspect karna — sab practical examples ke saath dekhoge.

HTTP kya hai

Ek line ka funda: HTTP stateless hai — har request apne aap mein poori hai, server ko yaad nahi rehta ki pichhli request kisne aayi thi. Isliye har request ke saath identity (token ya cookie) bhejni padti hai — authentication agle sections mein.

Request/response cycle — wire pe kya jaata hai

--- REQUEST (client se server) ---
POST /api/orders HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOi...

{"item": "gpu-hours", "qty": 2}

--- RESPONSE (server se client) ---
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/orders/981

{"id": 981, "status": "pending"}

• Request ke 4 hisse: method (kya karna hai), URL (kahan), headers (metadata — auth, content type), body (payload — JSON, form data).
• Response ke 3 hisse: status line (HTTP/1.1 201 Created), headers (Content-Type, rate-limit info), body (JSON/HTML/file).
• Server ke andar kya hota hai: routing (kaunsa handler), kaam (DB, external call), phir response serialize. Agle lesson mein tum yahi FastAPI se banoge.

Methods aur idempotency

GET    /orders        # padho — safe, repeat se kuch nahi badalta
POST   /orders        # naya banao — har call ek naya resource
PUT    /orders/981    # poora replace — do baar same result
PATCH  /orders/981    # thoda badlo (sirf given fields)
DELETE /orders/981    # hatao — doosri baar 404, lekin state same

• Idempotent ka matlab: wahi request ek baar aur das baar karne se final state same rehti hai. GET, PUT, DELETE idempotent hain; POST nahi.
• Kyun matter karta hai: timeout pe client retry karta hai. POST retry kiya toh do orders ban gaye; PUT retry kiya toh kuch nahi bigda.
• Duplicate POST se bachne ka tareeqa: client ek idempotency key (unique request id) bhejta hai, server use karke duplicate ignore karta hai.
• GET mein body mat bhejo — kai proxies aur clients use ignore ya fail kar dete hain. Filter/sort ke liye query params hain.

Status codes — families aur common codes

2xx  200 OK              201 Created (Location header ke saath)
     204 No Content       (delete success, body khaali)

4xx  400 Bad Request      client ne galat bheja (syntax/field)
     401 Unauthorized     login nahi hua (token do)
     403 Forbidden        login hai par permission nahi
     404 Not Found        resource hi nahi
     409 Conflict         state clash (duplicate, overlapping)
     422 Unprocessable    body parse hui par validation fail
     429 Too Many Requests  rate limit — thodi der baad try karo

5xx  500 Internal Server Error   server ka bug
     502/503/504                 upstream down/slow/missing

• 4xx vs 5xx: 4xx = client theek karo (tumhara code/inputs), 5xx = server/upstream ka issue (retry + log, tumhara fix nahi). Ye line interview mein aati hai.
• 200 vs 201: POST ke success mein 201 + Location header (naye resource ka URL). DELETE aksar 204 — body ki zarurat hi nahi.
• 401 vs 403: 401 = "pehchano" (token missing/expired), 403 = "pehchana par andar nahi".
• 429 par backoff laga kar retry karo — tight loop chalaya toh limit aur tez lag jaayegi.

Headers, params aur bodies

# Query params — filter, sort, pagination
curl -sS "https://api.example.com/orders?status=pending&page=2" -H "Accept: application/json"

# Path params — resource ka identity: /orders/981
curl -sS "https://api.example.com/orders/981"

# Body + Content-Type — server ko batana zaroori hai andar kya hai
curl -sS -X POST "https://api.example.com/orders" -H "Content-Type: application/json" -d "{\"item\": \"gpu-hours\", \"qty\": 2}"

• Headers = metadata: Content-Type (body kis format mein), Authorization (token), Accept (kya jawab chahiye), custom X-Request-Id jaise tracing ids.
• Path params resource ko identify karte hain (/orders/981), query params uska behavior tune karte hain (?status=pending).
• Body sirf POST/PUT/PATCH mein — aur Content-Type ke bina server andar ka format guess karega (ya 415 de dega).
• Cookies browser sessions ke liye hain — pure API clients mein aksar token header hi kaafi hota hai.

JSON ke saath confident kaam

import json

raw = "{\"id\": 981, \"qty\": 2, \"tags\": [\"rush\"]}"
order = json.loads(raw)             # string -> dict
order["qty"] += 1
text = json.dumps(order, indent=2)  # dict -> string

# Common traps
type(json.loads("1"))               # int — JSON number Python int/float banta hai
json.loads("None")                  # error — Python literal nahi, JSON hai
json.loads("{bad}")                 # error — pehle check karo ki body JSON hai

• JSON ke rules: keys double quotes mein, trailing comma nahi, null/true/false (chhote letters), comment nahi. Python dict thoda alag chalta hai — isliye dumps/loads se hi guzaro.
• Pehle status, phir body: 500 ka jawab aksar JSON nahi HTML hota hai — andha json.loads kiya toh exception mil jaayega jo asli problem chhupa dega.
• Validation JSON parse se alag hai: JSON sahi hone se schema sahi nahi hota. Field ka type/limit check Pydantic (agle lesson) se hota hai.
• Nested JSON: data["a"]["b"][0] — beech mein key missing ho toh .get() ya try/except se handle karo, warna KeyError crash.

RESTful resource design

GET    /orders               # list (?status=, ?page=)
POST   /orders               # create            -> 201
GET    /orders/981           # one               -> 200 | 404
PATCH  /orders/981           # partial update    -> 200 | 409
DELETE /orders/981           # remove            -> 204 | 404

GET    /orders/981/items     # nested collection (lekin sirf 1 level tak)

# GALAT — verbs URLs mein
POST /getOrderById    GET /deleteOrder/981    /createNewOrder

• URL mein noun, method mein verb: /orders (resource) + GET/POST (kaam). Verb URL mein daala toh wo REST nahi, RPC ban gaya.
• Plural nouns: /orders, /users — consistency hi API ki readability hai.
• Nesting shallow rakho: /orders/981/items theek hai, /teams/5/projects/9/members/2 jaisi lambi chain mushkil maintain hoti hai.
• Filters query params mein, identity path mein, versioning prefix mein (/v1/orders) — purana client toota na ho.

Authentication basics aur API debugging

# SAHI — secret header mein
curl -sS "https://api.example.com/me" -H "Authorization: Bearer $API_KEY"

# GALAT — secret URL mein (logs, browser history, proxies sab dekh lete hain)
curl -sS "https://api.example.com/me?api_key=sk-1234"

# Debug flags
curl -i -sS "https://api.example.com/orders/981"   # headers + body ek saath
curl -v -sS "https://api.example.com/orders/981"   # wire-level detail (TLS, redirect)

• API key ek static secret hai (server-side config mein rakho), bearer token aksar short-lived hota hai (login/refresh se milta hai) aur Authorization: Bearer ... header mein jaata hai.
• Secrets kabhi URL mein nahi: query strings server logs, proxies aur browser history mein jaake rehti hain. Header hamesha.
• Tools: curl (CLI, scriptable), Postman/Bruno (saved collections, environments), ya seedha Python httpx. Debug ka pattern same hai — request banao, status padho, body parse karo.
• Response mein X-Request-Id jaisa header note karo — support team ko dikhane par wo exact request dhoond leti hai.

Exercise

Common mistakes

• Secrets ko URL/query string mein bhejna: api_key=... links logs, history aur analytics tak pahunch jaate hain. Fix: Authorization header, aur keys ko env/config se load karo.
• Status check kiye bina JSON parse karna: Error responses aksar JSON nahi hote — andha loads kiya toh crash asli error chhupa dega. Fix: pehle resp.raise_for_status() ya status check, phir body parse.
• Sirf 200 ko success manna: POST ke liye 201 aur DELETE ke liye 204 bhi success hain — == 200 check se valid responses reject ho jaate hain. Fix: 2xx family treat karo.
• GET se mutation karwana: Browser refresh ya prefetch ne automatically GET bheja toh order dobara ban gaya. Fix: mutation hamesha POST/PUT/PATCH se, aur POST pe idempotency key rakho.

REQUEST   : GET /orders/981 + headers        (Client -> Server)
SERVER    : routing -> order dhoondo -> (na mila toh status decide)
RESPONSE  : 404 Not Found + {"error": "not found"}  (Server -> Client)

Jo kuch curl se dekhte ho wahi browser bhi karta hai — fark sirf automation ka hai.