REST API Design Fundamentals

# FastAPI Status Code Example
from fastapi import FastAPI, HTTPException, status

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    user = await db.get_user(user_id)

    if not user:
        # Return 404 if user doesn't exist
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"User {user_id} not found"
        )

    # Return 200 with user data
    return user

# Result: GET /users/999 → 404 with error message

from fastapi import FastAPI, HTTPException, status, Response
from pydantic import BaseModel, EmailStr
from typing import List, Optional
from datetime import datetime

app = FastAPI(title="Blog API", version="1.0.0")

# Data models
class PostCreate(BaseModel):
    title: str
    content: str
    author_email: EmailStr

class PostUpdate(BaseModel):
    title: Optional[str] = None
    content: Optional[str] = None

class Post(BaseModel):
    id: int
    title: str
    content: str
    author_email: str
    created_at: datetime
    updated_at: datetime

# In-memory database (use real database in production)
posts_db = {}
post_id_counter = 1

# GET /posts - List all posts
@app.get("/posts", response_model=List[Post], status_code=200)
async def list_posts(
    limit: int = 10,
    offset: int = 0,
    author: Optional[str] = None
):
    """
    Retrieve a list of blog posts with pagination.

    - **limit**: Number of posts to return (default: 10)
    - **offset**: Number of posts to skip (default: 0)
    - **author**: Filter by author email (optional)
    """
    all_posts = list(posts_db.values())

    # Filter by author if provided
    if author:
        all_posts = [p for p in all_posts if p["author_email"] == author]

    # Apply pagination
    paginated = all_posts[offset:offset + limit]
    return paginated

# POST /posts - Create a new post
@app.post("/posts", response_model=Post, status_code=201)
async def create_post(post: PostCreate, response: Response):
    """
    Create a new blog post.

    Returns 201 Created with Location header pointing to new resource.
    """
    global post_id_counter

    new_post = {
        "id": post_id_counter,
        "title": post.title,
        "content": post.content,
        "author_email": post.author_email,
        "created_at": datetime.now(),
        "updated_at": datetime.now()
    }

    posts_db[post_id_counter] = new_post

    # Set Location header
    response.headers["Location"] = f"/posts/{post_id_counter}"

    post_id_counter += 1
    return new_post

# GET /posts/{post_id} - Get single post
@app.get("/posts/{post_id}", response_model=Post, status_code=200)
async def get_post(post_id: int):
    """
    Retrieve a specific blog post by ID.

    Returns 404 if post doesn't exist.
    """
    if post_id not in posts_db:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"Post {post_id} not found"
        )

    return posts_db[post_id]

# PUT /posts/{post_id} - Replace entire post
@app.put("/posts/{post_id}", response_model=Post, status_code=200)
async def replace_post(post_id: int, post: PostCreate):
    """
    Replace an entire blog post.

    All fields must be provided. Returns 404 if post doesn't exist.
    """
    if post_id not in posts_db:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"Post {post_id} not found"
        )

    # Keep original created_at, update everything else
    updated_post = {
        "id": post_id,
        "title": post.title,
        "content": post.content,
        "author_email": post.author_email,
        "created_at": posts_db[post_id]["created_at"],
        "updated_at": datetime.now()
    }

    posts_db[post_id] = updated_post
    return updated_post

# PATCH /posts/{post_id} - Partial update
@app.patch("/posts/{post_id}", response_model=Post, status_code=200)
async def update_post(post_id: int, updates: PostUpdate):
    """
    Partially update a blog post.

    Only provided fields are updated. Returns 404 if post doesn't exist.
    """
    if post_id not in posts_db:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"Post {post_id} not found"
        )

    post = posts_db[post_id]

    # Update only provided fields
    if updates.title is not None:
        post["title"] = updates.title
    if updates.content is not None:
        post["content"] = updates.content

    post["updated_at"] = datetime.now()
    posts_db[post_id] = post

    return post

# DELETE /posts/{post_id} - Delete post
@app.delete("/posts/{post_id}", status_code=204)
async def delete_post(post_id: int):
    """
    Delete a blog post.

    Returns 204 No Content on success, 404 if post doesn't exist.
    """
    if post_id not in posts_db:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"Post {post_id} not found"
        )

    del posts_db[post_id]
    return Response(status_code=status.HTTP_204_NO_CONTENT)

# Run with: uvicorn main:app --reload