Initial commit: FastAPI teaching tool

.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+.env
+*.egg-info/
+dist/
+build/

Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY app.py .
+
+EXPOSE 7860
+
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,134 @@
+---
+title: API Teaching Tool
+emoji: 🔌
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+license: mit
+---
+
+# API Teaching Tool
+
+A simple educational API for learning HTTP methods, request/response formats, and REST API concepts.
+
+## Quick Start
+
+Once deployed, visit `/docs` for interactive Swagger documentation.
+
+## Endpoints Overview
+
+### GET Examples
+| Endpoint | Description |
+|----------|-------------|
+| `/hello` | Simplest GET - returns greeting |
+| `/time` | Returns current server time |
+| `/greet?name=X` | Query parameter example |
+| `/greet/{name}` | Path parameter example |
+| `/search?q=X&limit=10` | Multiple query parameters |
+| `/items` | List all items |
+| `/items/{id}` | Get single item |
+
+### POST Examples
+| Endpoint | Description |
+|----------|-------------|
+| `/items` | Create new item (JSON body) |
+| `/users` | Create user (JSON body) |
+| `/echo` | Echo back any JSON you send |
+| `/echo/text` | Echo back raw text |
+
+### PUT/PATCH/DELETE
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/items/{id}` | PUT | Replace entire item |
+| `/items/{id}` | PATCH | Partial update |
+| `/items/{id}` | DELETE | Delete item |
+
+### Response Formats
+| Endpoint | Format |
+|----------|--------|
+| `/format/json` | JSON (default) |
+| `/format/text` | Plain text |
+| `/format/html` | HTML page |
+| `/format/xml` | XML document |
+
+### Educational
+| Endpoint | Description |
+|----------|-------------|
+| `/headers` | Shows all request headers |
+| `/headers/custom` | Returns custom headers |
+| `/status/{code}` | Returns specified HTTP status |
+| `/method` | Accepts any method, shows what was used |
+| `/ip` | Shows client IP address |
+| `/params/types` | Demonstrates parameter types |
+
+## Example Usage
+
+### Using curl
+
+```bash
+# Simple GET
+curl https://nipun-api-testing.hf.space/hello
+
+# GET with query parameter
+curl "https://nipun-api-testing.hf.space/greet?name=Alice"
+
+# POST with JSON body
+curl -X POST https://nipun-api-testing.hf.space/items \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Book", "price": 15.99, "quantity": 10}'
+
+# PUT to update
+curl -X PUT https://nipun-api-testing.hf.space/items/1 \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Updated Apple", "price": 2.00, "quantity": 50}'
+
+# DELETE
+curl -X DELETE https://nipun-api-testing.hf.space/items/1
+
+# Get different formats
+curl https://nipun-api-testing.hf.space/format/xml
+curl https://nipun-api-testing.hf.space/format/html
+
+# Test status codes
+curl -i https://nipun-api-testing.hf.space/status/404
+curl -i https://nipun-api-testing.hf.space/status/201
+```
+
+### Using Python requests
+
+```python
+import requests
+
+BASE = "https://nipun-api-testing.hf.space"
+
+# GET request
+response = requests.get(f"{BASE}/hello")
+print(response.json())
+
+# GET with parameters
+response = requests.get(f"{BASE}/greet", params={"name": "Alice"})
+print(response.json())
+
+# POST with JSON
+data = {"name": "Laptop", "price": 999.99, "quantity": 5}
+response = requests.post(f"{BASE}/items", json=data)
+print(response.status_code)  # 201
+print(response.json())
+
+# Check headers
+response = requests.get(f"{BASE}/headers")
+print(response.json())
+```
+
+## Local Development
+
+```bash
+pip install -r requirements.txt
+python app.py
+# Visit http://localhost:7860/docs
+```
+
+## License
+
+MIT

app.py

@@ -0,0 +1,418 @@
+"""
+Educational API for Teaching HTTP Methods & Response Formats
+============================================================
+A simple FastAPI application designed for teaching REST API concepts.
+
+Endpoints cover:
+- HTTP Methods: GET, POST, PUT, DELETE, PATCH
+- Response Formats: JSON, XML, Plain Text, HTML
+- Query Parameters, Path Parameters, Request Bodies
+- Headers, Status Codes, and more
+"""
+
+from fastapi import FastAPI, Query, Path, Body, Header, Response, HTTPException, Request
+from fastapi.responses import PlainTextResponse, HTMLResponse, JSONResponse
+from pydantic import BaseModel, Field
+from typing import Optional, List
+from datetime import datetime
+import json
+
+app = FastAPI(
+    title="API Teaching Tool",
+    description="Educational API for learning HTTP methods, parameters, and response formats",
+    version="1.0.0",
+)
+
+# ============================================================================
+# DATA MODELS
+# ============================================================================
+
+class Item(BaseModel):
+    """A simple item model for POST/PUT examples"""
+    name: str = Field(..., example="Laptop")
+    price: float = Field(..., example=999.99)
+    quantity: int = Field(default=1, example=5)
+    description: Optional[str] = Field(default=None, example="A powerful laptop")
+
+class User(BaseModel):
+    """User model for registration examples"""
+    username: str = Field(..., example="john_doe")
+    email: str = Field(..., example="john@example.com")
+    age: Optional[int] = Field(default=None, example=25)
+
+class Message(BaseModel):
+    """Simple message model"""
+    text: str = Field(..., example="Hello, World!")
+
+# In-memory storage for demo purposes
+items_db = {
+    1: {"id": 1, "name": "Apple", "price": 1.50, "quantity": 100, "description": "Fresh red apple"},
+    2: {"id": 2, "name": "Banana", "price": 0.75, "quantity": 150, "description": "Yellow banana"},
+    3: {"id": 3, "name": "Orange", "price": 2.00, "quantity": 80, "description": "Juicy orange"},
+}
+next_id = 4
+
+# ============================================================================
+# ROOT & INFO ENDPOINTS
+# ============================================================================
+
+@app.get("/", tags=["Info"])
+def root():
+    """Welcome endpoint with API overview"""
+    return {
+        "message": "Welcome to the API Teaching Tool!",
+        "documentation": "/docs",
+        "endpoints": {
+            "GET examples": ["/hello", "/items", "/items/{id}", "/greet"],
+            "POST examples": ["/items", "/echo", "/users"],
+            "PUT examples": ["/items/{id}"],
+            "DELETE examples": ["/items/{id}"],
+            "PATCH examples": ["/items/{id}"],
+            "Response formats": ["/format/json", "/format/text", "/format/html", "/format/xml"],
+            "Educational": ["/echo", "/headers", "/status/{code}", "/delay/{seconds}"],
+        }
+    }
+
+# ============================================================================
+# SIMPLE GET ENDPOINTS
+# ============================================================================
+
+@app.get("/hello", tags=["GET Examples"])
+def hello():
+    """Simplest GET endpoint - returns a greeting"""
+    return {"message": "Hello, World!"}
+
+@app.get("/time", tags=["GET Examples"])
+def get_time():
+    """Returns current server time"""
+    now = datetime.now()
+    return {
+        "current_time": now.isoformat(),
+        "timestamp": now.timestamp(),
+        "formatted": now.strftime("%B %d, %Y at %I:%M %p")
+    }
+
+@app.get("/greet", tags=["GET Examples"])
+def greet(name: str = Query(default="Guest", description="Your name")):
+    """GET with query parameter - /greet?name=YourName"""
+    return {"message": f"Hello, {name}!", "parameter_received": name}
+
+@app.get("/greet/{name}", tags=["GET Examples"])
+def greet_path(name: str = Path(..., description="Your name in the URL path")):
+    """GET with path parameter - /greet/YourName"""
+    return {"message": f"Hello, {name}!", "path_parameter": name}
+
+@app.get("/search", tags=["GET Examples"])
+def search(
+    q: str = Query(..., description="Search query (required)"),
+    limit: int = Query(default=10, ge=1, le=100, description="Max results"),
+    offset: int = Query(default=0, ge=0, description="Skip first N results"),
+    sort: str = Query(default="relevance", description="Sort by: relevance, date, name")
+):
+    """GET with multiple query parameters - demonstrates pagination"""
+    return {
+        "query": q,
+        "limit": limit,
+        "offset": offset,
+        "sort": sort,
+        "explanation": "This shows how query parameters work for filtering/pagination",
+        "example_url": f"/search?q={q}&limit={limit}&offset={offset}&sort={sort}"
+    }
+
+# ============================================================================
+# CRUD OPERATIONS ON ITEMS
+# ============================================================================
+
+@app.get("/items", tags=["CRUD - Items"])
+def list_items():
+    """GET all items"""
+    return {"items": list(items_db.values()), "count": len(items_db)}
+
+@app.get("/items/{item_id}", tags=["CRUD - Items"])
+def get_item(item_id: int = Path(..., description="The ID of the item to retrieve")):
+    """GET a single item by ID"""
+    if item_id not in items_db:
+        raise HTTPException(status_code=404, detail=f"Item with id {item_id} not found")
+    return items_db[item_id]
+
+@app.post("/items", status_code=201, tags=["CRUD - Items"])
+def create_item(item: Item):
+    """POST - Create a new item"""
+    global next_id
+    new_item = {"id": next_id, **item.model_dump()}
+    items_db[next_id] = new_item
+    next_id += 1
+    return {"message": "Item created successfully", "item": new_item}
+
+@app.put("/items/{item_id}", tags=["CRUD - Items"])
+def update_item(item_id: int, item: Item):
+    """PUT - Replace an entire item"""
+    if item_id not in items_db:
+        raise HTTPException(status_code=404, detail=f"Item with id {item_id} not found")
+    updated_item = {"id": item_id, **item.model_dump()}
+    items_db[item_id] = updated_item
+    return {"message": "Item updated successfully", "item": updated_item}
+
+@app.patch("/items/{item_id}", tags=["CRUD - Items"])
+def partial_update_item(
+    item_id: int,
+    name: Optional[str] = Body(default=None),
+    price: Optional[float] = Body(default=None),
+    quantity: Optional[int] = Body(default=None),
+    description: Optional[str] = Body(default=None)
+):
+    """PATCH - Partially update an item (only send fields to change)"""
+    if item_id not in items_db:
+        raise HTTPException(status_code=404, detail=f"Item with id {item_id} not found")
+
+    current_item = items_db[item_id]
+    if name is not None:
+        current_item["name"] = name
+    if price is not None:
+        current_item["price"] = price
+    if quantity is not None:
+        current_item["quantity"] = quantity
+    if description is not None:
+        current_item["description"] = description
+
+    return {"message": "Item partially updated", "item": current_item}
+
+@app.delete("/items/{item_id}", tags=["CRUD - Items"])
+def delete_item(item_id: int):
+    """DELETE - Remove an item"""
+    if item_id not in items_db:
+        raise HTTPException(status_code=404, detail=f"Item with id {item_id} not found")
+    deleted_item = items_db.pop(item_id)
+    return {"message": "Item deleted successfully", "deleted_item": deleted_item}
+
+# ============================================================================
+# POST EXAMPLES
+# ============================================================================
+
+@app.post("/users", status_code=201, tags=["POST Examples"])
+def create_user(user: User):
+    """POST - Create a new user (demonstrates JSON body)"""
+    return {
+        "message": "User created successfully",
+        "user": user.model_dump(),
+        "note": "In a real app, this would save to a database"
+    }
+
+@app.post("/echo", tags=["POST Examples"])
+def echo_body(data: dict = Body(...)):
+    """POST - Echo back whatever JSON you send"""
+    return {
+        "received": data,
+        "type": str(type(data).__name__),
+        "keys": list(data.keys()) if isinstance(data, dict) else None
+    }
+
+@app.post("/echo/text", tags=["POST Examples"])
+async def echo_text(request: Request):
+    """POST - Echo back raw text body"""
+    body = await request.body()
+    return {
+        "received": body.decode("utf-8"),
+        "length": len(body),
+        "content_type": request.headers.get("content-type", "not specified")
+    }
+
+# ============================================================================
+# DIFFERENT RESPONSE FORMATS
+# ============================================================================
+
+@app.get("/format/json", tags=["Response Formats"])
+def format_json():
+    """Returns data as JSON (default)"""
+    return {
+        "format": "JSON",
+        "content_type": "application/json",
+        "data": {"name": "Alice", "age": 30, "city": "Mumbai"}
+    }
+
+@app.get("/format/text", response_class=PlainTextResponse, tags=["Response Formats"])
+def format_text():
+    """Returns data as plain text"""
+    return """Format: Plain Text
+Content-Type: text/plain
+
+Name: Alice
+Age: 30
+City: Mumbai
+
+This is plain text - no special formatting!"""
+
+@app.get("/format/html", response_class=HTMLResponse, tags=["Response Formats"])
+def format_html():
+    """Returns data as HTML"""
+    return """
+<!DOCTYPE html>
+<html>
+<head>
+    <title>HTML Response</title>
+    <style>
+        body { font-family: Arial, sans-serif; padding: 20px; }
+        .card { border: 1px solid #ddd; padding: 15px; border-radius: 8px; max-width: 300px; }
+        h1 { color: #333; }
+    </style>
+</head>
+<body>
+    <h1>HTML Response Example</h1>
+    <div class="card">
+        <h2>User Info</h2>
+        <p><strong>Name:</strong> Alice</p>
+        <p><strong>Age:</strong> 30</p>
+        <p><strong>City:</strong> Mumbai</p>
+    </div>
+    <p><em>Content-Type: text/html</em></p>
+</body>
+</html>
+"""
+
+@app.get("/format/xml", tags=["Response Formats"])
+def format_xml():
+    """Returns data as XML"""
+    xml_content = """<?xml version="1.0" encoding="UTF-8"?>
+<response>
+    <format>XML</format>
+    <content_type>application/xml</content_type>
+    <data>
+        <user>
+            <name>Alice</name>
+            <age>30</age>
+            <city>Mumbai</city>
+        </user>
+    </data>
+</response>"""
+    return Response(content=xml_content, media_type="application/xml")
+
+# ============================================================================
+# EDUCATIONAL ENDPOINTS
+# ============================================================================
+
+@app.get("/headers", tags=["Educational"])
+def show_headers(request: Request):
+    """Shows all request headers sent by the client"""
+    headers_dict = dict(request.headers)
+    return {
+        "your_headers": headers_dict,
+        "common_headers_explained": {
+            "user-agent": "Identifies your browser/client",
+            "accept": "What content types you accept",
+            "host": "The server you're connecting to",
+            "content-type": "Format of data you're sending (for POST/PUT)"
+        }
+    }
+
+@app.get("/headers/custom", tags=["Educational"])
+def custom_header_response():
+    """Returns a response with custom headers"""
+    content = {"message": "Check the response headers!"}
+    headers = {
+        "X-Custom-Header": "Hello from the server!",
+        "X-Request-Time": datetime.now().isoformat(),
+        "X-API-Version": "1.0.0"
+    }
+    return JSONResponse(content=content, headers=headers)
+
+@app.get("/status/{code}", tags=["Educational"])
+def return_status_code(
+    code: int = Path(..., description="HTTP status code to return (100-599)")
+):
+    """Returns the specified HTTP status code - useful for testing error handling"""
+    status_messages = {
+        200: "OK - Request succeeded",
+        201: "Created - Resource created successfully",
+        204: "No Content - Success but no content to return",
+        400: "Bad Request - Invalid request syntax",
+        401: "Unauthorized - Authentication required",
+        403: "Forbidden - Access denied",
+        404: "Not Found - Resource doesn't exist",
+        405: "Method Not Allowed - Wrong HTTP method",
+        500: "Internal Server Error - Server error",
+        502: "Bad Gateway - Invalid response from upstream",
+        503: "Service Unavailable - Server temporarily unavailable",
+    }
+
+    if code < 100 or code > 599:
+        raise HTTPException(status_code=400, detail="Status code must be between 100 and 599")
+
+    message = status_messages.get(code, f"Status code {code}")
+
+    if code >= 400:
+        raise HTTPException(status_code=code, detail=message)
+
+    return JSONResponse(
+        status_code=code,
+        content={"status_code": code, "message": message}
+    )
+
+@app.api_route("/method", methods=["GET", "POST", "PUT", "DELETE", "PATCH"], tags=["Educational"])
+async def show_method(request: Request):
+    """Accepts any HTTP method and shows what was used"""
+    body = None
+    if request.method in ["POST", "PUT", "PATCH"]:
+        try:
+            body = await request.json()
+        except:
+            body = (await request.body()).decode("utf-8") or None
+
+    return {
+        "method_used": request.method,
+        "method_explanation": {
+            "GET": "Retrieve data (no body)",
+            "POST": "Create new resource (has body)",
+            "PUT": "Replace entire resource (has body)",
+            "PATCH": "Partial update (has body)",
+            "DELETE": "Remove resource (usually no body)"
+        }.get(request.method, "Unknown method"),
+        "body_received": body,
+        "url": str(request.url),
+        "query_params": dict(request.query_params)
+    }
+
+@app.get("/ip", tags=["Educational"])
+def get_client_ip(request: Request):
+    """Returns the client's IP address"""
+    forwarded = request.headers.get("x-forwarded-for")
+    if forwarded:
+        ip = forwarded.split(",")[0].strip()
+    else:
+        ip = request.client.host if request.client else "unknown"
+
+    return {
+        "ip": ip,
+        "note": "Behind a proxy, this shows the proxy's IP unless X-Forwarded-For is set"
+    }
+
+# ============================================================================
+# QUERY PARAMETER TYPES
+# ============================================================================
+
+@app.get("/params/types", tags=["Parameter Examples"])
+def parameter_types(
+    string_param: str = Query(default="hello", description="A string parameter"),
+    int_param: int = Query(default=42, description="An integer parameter"),
+    float_param: float = Query(default=3.14, description="A float parameter"),
+    bool_param: bool = Query(default=True, description="A boolean parameter"),
+    list_param: List[str] = Query(default=["a", "b"], description="A list parameter")
+):
+    """Demonstrates different query parameter types"""
+    return {
+        "parameters_received": {
+            "string_param": {"value": string_param, "type": "str"},
+            "int_param": {"value": int_param, "type": "int"},
+            "float_param": {"value": float_param, "type": "float"},
+            "bool_param": {"value": bool_param, "type": "bool"},
+            "list_param": {"value": list_param, "type": "list"}
+        },
+        "example_url": "/params/types?string_param=test&int_param=100&float_param=2.5&bool_param=false&list_param=x&list_param=y"
+    }
+
+# ============================================================================
+# RUN SERVER (for local development)
+# ============================================================================
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=7860)

requirements.txt

@@ -0,0 +1,3 @@
+fastapi>=0.104.0
+uvicorn[standard]>=0.24.0
+pydantic>=2.0.0