TypeScript / Python API Tutorial

ts-python-api-tutorial/
├── nextjs/          # Next.js app (UI + API route handlers)        → port 3000
├── express/         # Express.js REST API                          → port 3001
├── nestjs/          # NestJS REST API                              → port 3002
├── flask-api/       # Flask REST API (Python, managed with UV)     → port 3003
├── fastapi-api/     # FastAPI REST API (Python, managed with UV)   → port 3004
├── docs/            # Per-tab documentation
│   ├── nextjs.md
│   ├── express.md
│   ├── nestjs.md
│   ├── advanced-nestjs.md
│   ├── flask.md
│   ├── fastapi.md
│   └── concepts.md
└── scripts/
    └── start-servers.sh  # Starts all tutorial servers (Ctrl-C to stop all)

• Node.js ≥ 20.9 (required by Next.js 16)
• npm — comes with Node.js
• Python ≥ 3.9 and UV — for the Flask and FastAPI tabs

# Next.js
cd nextjs && npm install

# Express
cd ../express && npm install

# NestJS
cd ../nestjs && npm install

# Flask (UV creates the virtual environment automatically on first run)
# No manual install step needed — UV handles it when you start the server.

# FastAPI — sync dependencies once to create the virtual environment
cd ../fastapi-api && uv sync

./scripts/start-servers.sh

// GET /api/items
export async function GET() {
  return NextResponse.json(items);
}

// POST /api/items
export async function POST(request: NextRequest) {
  const body = await request.json();
  const { name, description } = createItemSchema.parse(body); // throws if invalid
  const newItem = { id: nextId++, name, description };
  items.push(newItem);
  return NextResponse.json(newItem, { status: 201 });
}

// nextjs/app/lib/schemas.ts
import { z } from "zod";

export const createItemSchema = z.object({
  name: z.string().min(1, "Name is required"),
  description: z.string().optional().default(""),
});

export const patchItemSchema = z.object({
  name: z.string().min(1, "Name must not be empty").optional(),
  description: z.string().optional(),
});

# List all items
curl http://localhost:3000/api/items

# Create an item
curl -X POST http://localhost:3000/api/items \
  -H "Content-Type: application/json" \
  -d '{"name":"My Item","description":"Hello from curl"}'

# Update an item (replace 1 with the actual id)
curl -X PUT http://localhost:3000/api/items/1 \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated Name","description":"Updated desc"}'

# Delete an item
curl -X DELETE http://localhost:3000/api/items/1

import express from "express";
import cors from "cors";

const app = express();
const PORT = 3001;

// Allow requests from the Next.js dev server (port 3000)
app.use(cors({ origin: "http://localhost:3000" }));

// Parse JSON request bodies automatically
app.use(express.json());

// GET /api/items — list all items
app.get("/api/items", (_req, res) => {
  res.json(items);
});

// POST /api/items — create a new item
app.post("/api/items", (req, res) => {
  const { name, description } = createItemSchema.parse(req.body);
  const newItem = { id: nextId++, name, description };
  items.push(newItem);
  res.status(201).json(newItem);
});

// PUT /api/items/:id — full update
app.put("/api/items/:id", (req, res) => {
  const index = items.findIndex(i => i.id === Number(req.params.id));
  if (index === -1) { res.status(404).json({ error: "Item not found" }); return; }
  const { name, description } = updateItemSchema.parse(req.body);
  items[index] = { id: Number(req.params.id), name, description };
  res.json(items[index]);
});

// DELETE /api/items/:id
app.delete("/api/items/:id", (req, res) => {
  const index = items.findIndex(i => i.id === Number(req.params.id));
  if (index === -1) { res.status(404).json({ error: "Item not found" }); return; }
  const deleted = items.splice(index, 1)[0];
  res.json(deleted);
});

app.use((err, _req, res, _next) => {
  if (err instanceof ZodError) {
    res.status(400).json({ error: err.issues[0]?.message ?? "Validation error" });
    return;
  }
  console.error(err);
  res.status(500).json({ error: "Internal server error" });
});

# List all items
curl http://localhost:3001/api/items

# Create an item
curl -X POST http://localhost:3001/api/items \
  -H "Content-Type: application/json" \
  -d '{"name":"Express Item","description":"Created via curl"}'

# Update an item
curl -X PUT http://localhost:3001/api/items/1 \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated","description":"New description"}'

# Delete an item
curl -X DELETE http://localhost:3001/api/items/1

import "reflect-metadata";
import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.enableCors({ origin: "http://localhost:3000" });
  await app.listen(3002);
}

bootstrap();

@Controller("api/items")
export class ItemsController {

  @Get()
  findAll(): Item[] {
    return items;
  }

  @Post()
  @HttpCode(HttpStatus.CREATED)
  create(@Body() body: unknown): Item {
    const { name, description } = createItemSchema.parse(body);
    const newItem = { id: nextId++, name, description };
    items.push(newItem);
    return newItem;
  }

  @Get(":id")
  findOne(@Param("id", ParseIntPipe) id: number): Item {
    const item = items.find(i => i.id === id);
    if (!item) throw new NotFoundException("Item not found");
    return item;
  }

  @Delete(":id")
  remove(@Param("id", ParseIntPipe) id: number): Item {
    const index = items.findIndex(i => i.id === id);
    if (index === -1) throw new NotFoundException("Item not found");
    return items.splice(index, 1)[0];
  }
}

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

# List all items
curl http://localhost:3002/api/items

# Create an item
curl -X POST http://localhost:3002/api/items \
  -H "Content-Type: application/json" \
  -d '{"name":"NestJS Item","description":"Created via curl"}'

# Update an item
curl -X PUT http://localhost:3002/api/items/1 \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated","description":"New description"}'

# Delete an item
curl -X DELETE http://localhost:3002/api/items/1

@Injectable()
export class ApiKeyGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    const apiKey = request.headers["x-api-key"];
    if (apiKey !== "secret-key-123") {
      throw new BadRequestException(
        "Invalid or missing API key (use x-api-key: secret-key-123)"
      );
    }
    return true;
  }
}

// Apply the guard to an entire controller
@Controller("api/advanced")
@UseGuards(ApiKeyGuard)
export class AdvancedController { ... }

// Step 1 — Create a custom decorator
export const Public = () => SetMetadata("isPublic", true);

// Step 2 — Read the metadata inside the guard
canActivate(context: ExecutionContext): boolean {
  const isPublic = this.reflector.getAllAndOverride<boolean>("isPublic", [
    context.getHandler(),
    context.getClass(),
  ]);
  if (isPublic) return true; // skip the API key check
  // ... normal API key check
}

// Step 3 — Use the decorator on a route
@Get("public")
@Public()   // ← this route bypasses the guard
publicEndpoint() {
  return { message: "No API key needed!" };
}

@Injectable()
export class WrapResponseInterceptor<T>
  implements NestInterceptor<T, { success: boolean; data: T; timestamp: string }>
{
  intercept(context: ExecutionContext, next: CallHandler<T>) {
    return next.handle().pipe(
      map((data) => ({
        success: true,
        data,
        timestamp: new Date().toISOString(),
      }))
    );
  }
}

// Every response from this controller now looks like:
// { "success": true, "timestamp": "...", "data": { ...original... } }

// Abstract contract
export abstract class GreetingService {
  abstract getRandomGreeting(): string;
}

// Two concrete implementations
@Injectable()
export class HumanGreetingService extends GreetingService {
  private readonly greetings = ["Hello", "Hola", "Bonjour", "Ciao", "こんにちは"];
  getRandomGreeting() { return this.greetings[Math.floor(Math.random() * this.greetings.length)]; }
}

// Bind in AppModule — change useClass here to swap implementations
@Module({
  providers: [
    { provide: GreetingService, useClass: HumanGreetingService },
  ],
})
export class AppModule {}

// Controller is unaware of the concrete class
@Controller("api/advanced")
export class AdvancedController {
  constructor(private greetingService: GreetingService) {}

  @Get("di")
  @Public()
  dependencyInjectionDemo() {
    return { greeting: this.greetingService.getRandomGreeting() };
  }
}

# Public endpoint — no API key needed
curl http://localhost:3002/api/advanced/public

# Guarded endpoint — correct key (response is wrapped by the interceptor)
curl http://localhost:3002/api/advanced/guarded \
  -H "x-api-key: secret-key-123"

# Guarded endpoint — wrong key → 400 error
curl http://localhost:3002/api/advanced/guarded \
  -H "x-api-key: wrong-key"

# DI demo — no API key needed (marked @Public())
curl http://localhost:3002/api/advanced/di

# From the flask-api/ directory
uv run python main.py

# GET /api/items — list all items
@app.route("/api/items", methods=["GET"])
def list_items():
    with _lock:
        return jsonify(list(_items.values())), 200

# POST /api/items — create a new item
@app.route("/api/items", methods=["POST"])
def create_item():
    global _next_id
    body = request.get_json(silent=True) or {}
    try:
        data = CreateItemSchema.model_validate(body)
    except ValidationError as exc:
        first_error = exc.errors()[0]
        return jsonify({"error": first_error["msg"]}), 422

    with _lock:
        item_id = _next_id
        _next_id += 1
        item = {"id": item_id, "name": data.name, "description": data.description}
        _items[item_id] = item
    return jsonify(item), 201

# DELETE /api/items/<id>
@app.route("/api/items/<int:item_id>", methods=["DELETE"])
def delete_item(item_id: int):
    with _lock:
        item = _items.pop(item_id, None)
    if item is None:
        return jsonify({"error": f"Item {item_id} not found"}), 404
    return jsonify({"message": f"Item {item_id} deleted"}), 200

from pydantic import BaseModel, ValidationError, field_validator
from typing import Optional

class CreateItemSchema(BaseModel):
    name: str
    description: Optional[str] = ""

    @field_validator("name")
    @classmethod
    def name_must_not_be_empty(cls, v: str) -> str:
        v = v.strip()
        if not v:
            raise ValueError("Name is required and cannot be empty")
        if len(v) < 2:
            raise ValueError("Name must be at least 2 characters")
        return v

# List all items
curl http://localhost:3003/api/items

# Create an item
curl -X POST http://localhost:3003/api/items \
  -H "Content-Type: application/json" \
  -d '{"name":"Flask Item","description":"Created via curl"}'

# Try an invalid body — Pydantic will reject it
curl -X POST http://localhost:3003/api/items \
  -H "Content-Type: application/json" \
  -d '{"name":"x"}'

# Update an item (replace 1 with the actual id)
curl -X PUT http://localhost:3003/api/items/1 \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated Flask Item","description":"New description"}'

# Delete an item
curl -X DELETE http://localhost:3003/api/items/1

from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# CORSMiddleware handles preflight requests automatically
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
)

# GET /api/items — list all items
@app.get("/api/items")
def list_items():
    with _lock:
        return list(_items.values())

# POST /api/items — FastAPI validates body: CreateItemSchema automatically
@app.post("/api/items", status_code=201)
def create_item(body: CreateItemSchema):
    global _next_id
    with _lock:
        item_id = _next_id
        _next_id += 1
        item = {"id": item_id, "name": body.name, "description": body.description}
        _items[item_id] = item
    return item

# GET /api/items/{item_id} — path parameter typed as int
@app.get("/api/items/{item_id}")
def get_item(item_id: int):
    with _lock:
        item = _items.get(item_id)
    if item is None:
        raise HTTPException(status_code=404, detail=f"Item {item_id} not found")
    return item

# DELETE /api/items/{item_id}
@app.delete("/api/items/{item_id}")
def delete_item(item_id: int):
    with _lock:
        item = _items.pop(item_id, None)
    if item is None:
        raise HTTPException(status_code=404, detail=f"Item {item_id} not found")
    return {"message": f"Item {item_id} deleted"}

# Flask — you call model_validate() manually and catch the exception
body = request.get_json(silent=True) or {}
try:
    data = CreateItemSchema.model_validate(body)
except ValidationError as exc:
    first_error = exc.errors()[0]
    return jsonify({"error": first_error["msg"]}), 422

# FastAPI — declare the schema as a parameter; FastAPI does the rest
@app.post("/api/items", status_code=201)
def create_item(body: CreateItemSchema):   # ← FastAPI validates automatically
    ...

# List all items
curl http://localhost:3004/api/items

# Create an item
curl -X POST http://localhost:3004/api/items \
  -H "Content-Type: application/json" \
  -d '{"name":"FastAPI Item","description":"Created via curl"}'

# Try an invalid body — Pydantic will reject it
curl -X POST http://localhost:3004/api/items \
  -H "Content-Type: application/json" \
  -d '{"name":"x"}'

# Update an item (replace 1 with the actual id)
curl -X PUT http://localhost:3004/api/items/1 \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated FastAPI Item","description":"New description"}'

# Delete an item
curl -X DELETE http://localhost:3004/api/items/1