api-route-design

API Route Design Skill

Expert design and implementation of RESTful APIs with proper validation, response formatting, and HTTP semantics.

Quick Reference

Pattern	Example	Purpose
List resource	@router.get("/fees/", response_model=List[FeeOut])	Retrieve collection
Get by ID	@router.get("/fees/{fee_id}")	Retrieve single resource
Create	@router.post("/fees/", response_model=FeeOut, status_code=201)	Create new resource
Update	@router.put("/fees/{fee_id}")	Full resource update
Patch	@router.patch("/fees/{fee_id}")	Partial resource update
Delete	@router.delete("/fees/{fee_id}", status_code=204)	Remove resource

URL Naming Conventions

/v1/{resource}           # Collection endpoints
/v1/{resource}/{id}      # Single resource endpoints
/v1/{resource}/{id}/sub  # Nested resource endpoints

Rules:

• Use lowercase, hyphens for multi-word: /student-fees not /studentFees
• Use plural nouns for collections: /users not /user
• Use HTTP methods semantically: GET (read), POST (create), PUT/PATCH (update), DELETE (remove)

HTTP Status Codes

Code	Usage	Example
200	OK	Successful GET, PUT, PATCH
201	Created	Successful POST (resource created)
202	Accepted	Async operation started
204	No Content	Successful DELETE
400	Bad Request	Invalid input, validation failed
401	Unauthorized	Missing or invalid auth
403	Forbidden	Authenticated but not authorized
404	Not Found	Resource doesn't exist
422	Unprocessable Entity	Validation errors (Pydantic)
500	Internal Server Error	Unexpected server error

Request Validation Patterns

Path Parameters

from fastapi import APIRouter, HTTPException
from typing import Annotated

router = APIRouter()

@router.get("/fees/{fee_id}")
async def get_fee(fee_id: int):
    fee = await get_fee_by_id(fee_id)
    if not fee:
        raise HTTPException(status_code=404, detail="Fee not found")
    return fee

Query Parameters (Pagination, Filtering, Sorting)