Python JSON, HTTP & APIs

What is JSON?

JSON means JavaScript Object Notation. Ye language-independent text format hai jo APIs, configuration aur data exchange me commonly use hota hai. JSON text Python dictionary nahi hota, although syntax similar lag sakti hai.

JSON values and Python types

• JSON object → Python dict.
• JSON array → Python list.
• JSON string → Python str.
• JSON number → usually Python int or float.
• true/false → True/False.
• null → None.

Parse JSON text with json.loads()

import json

text = '{"name": "Aman", "score": 88, "active": true}'
student = json.loads(text)

print(student["name"])
print(student["score"])
print(type(student))

json.loads() JSON string ko Python object me decode karta hai.

Try JSON parsing →

Create JSON text with json.dumps()

import json

data = {
    "course": "Python",
    "chapters": 24,
    "published": True,
}

text = json.dumps(data, indent=2)
print(text)

json.dumps() Python object ko JSON string me encode karta hai. indent human-readable formatting ke liye useful hai.

Unicode and ensure_ascii

import json

data = {"message": "Namaste भारत"}
print(json.dumps(data, ensure_ascii=False))

ensure_ascii=False Unicode characters ko readable form me preserve kar sakta hai. File/network encoding still UTF-8 explicitly handle karna good practice hai.

Read and write JSON files

import json

profile = {"name": "Riya", "skills": ["Python", "SQL"]}

with open("profile.json", "w", encoding="utf-8") as file:
    json.dump(profile, file, indent=2, ensure_ascii=False)

with open("profile.json", "r", encoding="utf-8") as file:
    restored = json.load(file)

print(restored)

dump/load file objects ke saath work karte hain; dumps/loads strings ke saath.

Invalid JSON and JSONDecodeError

import json

text = '{"name": "Aman",}'

try:
    data = json.loads(text)
except json.JSONDecodeError as error:
    print("Invalid JSON:", error.msg)

Trailing commas, single-quoted JSON property names, comments aur malformed syntax JSON parsing fail kara sakte hain.

Values JSON cannot serialize automatically

import json
from datetime import datetime, timezone

data = {
    "created_at": datetime.now(timezone.utc).isoformat()
}

print(json.dumps(data))

Datetime object ko directly serialize karne ke bajay machine-friendly string, jaise ISO 8601, me convert karna clear approach hai. Advanced code me custom encoders bhi possible hain.

What is an API?

API ek defined interface hai jiske through one software system another system se data ya functionality request kar sakta hai. Web APIs commonly HTTP use karti hain.

HTTP request and response model

Client request send karta hai; server response return karta hai. Request me method, URL, headers and optional body ho sakte hain. Response me status code, headers and optional body hota hai.

GET /api/students/42 HTTP/1.1
Host: example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{"id": 42, "name": "Aman"}

Common HTTP methods

• GET — data read/fetch.
• POST — commonly new resource/action create.
• PUT — commonly full replacement/update.
• PATCH — commonly partial update.
• DELETE — resource deletion request.

Exact semantics API documentation define karti hai; method name alone complete behavior guarantee nahi karta.

HTTP status codes

• 200 OK — successful response.
• 201 Created — resource successfully created.
• 204 No Content — success without response body.
• 400 Bad Request — request invalid.
• 401 Unauthorized — authentication missing/invalid.
• 403 Forbidden — authenticated but not permitted.
• 404 Not Found — resource/path not found.
• 409 Conflict — request conflicts with current state.
• 429 Too Many Requests — rate limit.
• 500+ — server-side failure category.

Production code me exact API contract read karo; status codes ko blindly one meaning me hard-code mat karo.

GET request with the standard library

import json
from urllib.request import Request, urlopen

request = Request(
    "https://api.example.com/students/42",
    headers={"Accept": "application/json"},
)

with urlopen(request, timeout=10) as response:
    body = response.read().decode("utf-8")
    data = json.loads(body)
    print(response.status)
    print(data)

timeout important hai; network call ko indefinitely wait karne dena poor reliability pattern hai.

Query parameters

from urllib.parse import urlencode

params = {"page": 2, "limit": 20, "search": "python basics"}
query = urlencode(params)
url = f"https://api.example.com/courses?{query}"
print(url)

Manual string concatenation se special characters break ho sakte hain; URL encoding tools use karo.

Send a JSON request body

import json
from urllib.request import Request, urlopen

payload = {"name": "Aman", "course": "Python"}
body = json.dumps(payload).encode("utf-8")

request = Request(
    "https://api.example.com/students",
    data=body,
    method="POST",
    headers={
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
)

with urlopen(request, timeout=10) as response:
    print(response.status)
    print(response.read().decode("utf-8"))

Content-Type: application/json server ko body format batata hai. Response ka content type separately inspect karna bhi useful hai.

Headers

HTTP headers request/response metadata carry karte hain. Common examples: Accept, Content-Type, Authorization, caching headers and rate-limit metadata.

Bearer token pattern

import os
from urllib.request import Request

token = os.environ.get("API_TOKEN")
if not token:
    raise RuntimeError("API_TOKEN is not configured")

request = Request(
    "https://api.example.com/me",
    headers={"Authorization": f"Bearer {token}"},
)

Logs me token print mat karo. Error reporting me request headers sanitize/redact karna bhi important hai.

Handle HTTP and network errors

from urllib.error import HTTPError, URLError
from urllib.request import urlopen

try:
    with urlopen("https://api.example.com/data", timeout=10) as response:
        print(response.status)
except HTTPError as error:
    print("HTTP error:", error.code)
except URLError as error:
    print("Network error:", error.reason)

HTTPError server HTTP response error represent karta hai; URLError DNS, connection ya lower-level network failures cover kar sakta hai.

Do not assume every response is valid JSON

import json

content_type = "application/json; charset=utf-8"
body = '{"ok": true}'

if "application/json" in content_type.lower():
    try:
        data = json.loads(body)
    except json.JSONDecodeError:
        data = None
else:
    data = None

print(data)

Status code, content type aur body shape all validate karo. Successful status bhi expected schema guarantee nahi karta.

Validate API response structure

response_data = {
    "student": {"id": 42, "name": "Aman"}
}

student = response_data.get("student")
if not isinstance(student, dict):
    raise ValueError("student object missing")

student_id = student.get("id")
name = student.get("name")

if not isinstance(student_id, int) or not isinstance(name, str):
    raise ValueError("unexpected API response shape")

print(student_id, name)

External API data ko trusted internal object automatically mat samjho. Required fields/types validate karo.

Try response validation →

REST-style API concepts

REST ek architectural style hai, one fixed wire protocol nahi. Practical REST-style APIs resources ko URLs se represent kar sakti hain and standard HTTP methods/status codes use karti hain.

GET    /students
GET    /students/42
POST   /students
PATCH  /students/42
DELETE /students/42

Real API may different conventions use kare. Documentation always source of truth hai.

Pagination

Large datasets ek response me return karna expensive ho sakta hai. APIs page/limit, offset, cursor ya next-link based pagination use kar sakti hain.

Rate limits

API provider request frequency limit kar sakta hai. 429, Retry-After ya provider-specific headers rate-limit information de sakte hain.

Retry immediately in a tight loop mat karo. Server guidance respect karo, bounded retries and backoff use karo, and non-idempotent operations ko automatically repeat karne se pehle consequences samjho.

Idempotency basics

Idempotent operation multiple identical requests ke baad same intended final state preserve karti hai. GET normally safe/idempotent semantics target karta hai; PUT and DELETE commonly idempotent design hote hain, while POST often nahi. Real API contract verify karo.

Popular third-party requests library — preview

Python ecosystem me requests package HTTP client code ko convenient banata hai, but it is not part of standard library. Chapter 22 me pip and virtual environments ke saath third-party packages properly install/manage karenge.

# Requires: pip install requests
import requests

response = requests.get(
    "https://api.example.com/data",
    timeout=10,
)
response.raise_for_status()
data = response.json()

Practice API logic without internet

API learning ke liye network mandatory nahi. JSON response string ko mock karke parsing, validation, filtering and error handling practice kar sakte ho.

import json

response_text = '''{
  "status": "success",
  "students": [
    {"id": 1, "name": "Aman", "score": 78},
    {"id": 2, "name": "Riya", "score": 92},
    {"id": 3, "name": "Kabir", "score": 35}
  ]
}'''

data = json.loads(response_text)

if data.get("status") != "success":
    raise RuntimeError("API reported failure")

students = data.get("students")
if not isinstance(students, list):
    raise ValueError("students must be a list")

passed = [
    student for student in students
    if isinstance(student, dict) and student.get("score", 0) >= 40
]

for student in passed:
    print(student["name"], student["score"])

Try mocked API data →

Common beginner mistakes

• Python dict literal ko JSON text samajhna.
• JSON me single quotes/comments/trailing comma expect karna.
• json.loads() and json.load() mix up karna.
• Every HTTP response ko valid JSON assume karna.
• Timeout omit karna.
• Only 200 ko success maan lena while API 201/204 use kar sakti hai.
• API key/token source code me hard-code karna.
• Sensitive headers/body logs me print karna.
• Response fields/types validate na karna.
• 429 ke baad aggressive retry loop chalana.
• POST operation ko blindly retry karna and duplicate resource create kar dena.
• URL query string manually concatenate karna.

Beginner best practices

• JSON boundary par parsing errors handle karo.
• UTF-8 explicitly use karo where practical.
• HTTP calls me reasonable timeout set karo.
• Status code + content type + expected JSON shape validate karo.
• Secrets environment/config secret store me rakho.
• Errors me enough context log karo but credentials redact karo.
• Retries bounded rakho and API guidance respect karo.
• Pagination/rate limits documentation read karo.
• Network code ko parsing/business logic se separate functions me rakho.

Chapter checklist

• json.loads(), json.dumps(), json.load(), json.dump() ka difference clear hai?
• JSON vs Python data types map kar sakte ho?
• HTTP request/response structure samajh aaya?
• GET/POST/PUT/PATCH/DELETE ka high-level purpose clear hai?
• Common 2xx/4xx/5xx status codes recognize kar sakte ho?
• Query params safely encode kar sakte ho?
• Timeout and network exceptions handle kar sakte ho?
• API response JSON ko validate kar sakte ho?
• API token ko source code se bahar rakhna samajh aaya?
• Pagination/rate-limit/retry basics clear hain?

Open practice starter →