API Design

1. Resource-Oriented Design

# Good: Nouns for resources
GET    /users              → List users
POST   /users              → Create user
GET    /users/{id}         → Get user
PUT    /users/{id}         → Replace user
PATCH  /users/{id}         → Update user fields
DELETE /users/{id}         → Delete user

GET    /users/{id}/posts   → User's posts (nested resource)

# Bad: Verbs in paths
POST /createUser
GET  /getUsers
POST /deleteUser/{id}

2. HTTP Status Codes (Use Them Correctly)

200 OK              — Success with body
201 Created         — Resource created (include Location header)
204 No Content      — Success, no body (DELETE, some PATCHes)
400 Bad Request     — Client sent invalid data
401 Unauthorized    — Not authenticated
403 Forbidden       — Authenticated but not authorized
404 Not Found       — Resource doesn't exist
409 Conflict        — State conflict (duplicate, version mismatch)
422 Unprocessable   — Validation failed
429 Too Many Req.   — Rate limited
500 Internal Error  — Server bug (should never leak details)

3. Consistent Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {"field": "email", "message": "Invalid email format"},
      {"field": "age", "message": "Must be 18 or older"}
    ]
  }
}

Always: same error shape across all endpoints. Never: different error formats in different routes.

Error translation layer — one level, not two. When the API boundary is the only consumer, translate raw storage/driver exceptions (IntegrityError, NoResultFound, deadlocks) directly to HTTPException subclasses in one shared helper (as_api_exception(work, *, context)) called by every route. Skip the extra "domain error → HTTP error" mapping layer — it pays a class-tree tax for zero decoupling gain when there's no non-HTTP consumer. Logic-layer code raises HTTPException subclasses directly; FastAPI's native handler renders them. Introduce a domain-error indirection ONLY when a second entry-point shape (SQS consumer, cron, CLI) needs the same mapping — then the domain classes earn their weight.

4. Versioning

/api/v1/users    — URL versioning (most common, visible)
/api/v2/users    — New version for breaking changes

5. Pagination

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "has_next": true
  }
}

6. Input Validation at Boundary

# FastAPI with Pydantic
class CreateUserRequest(BaseModel):
    email: EmailStr
    name: str = Field(min_length=1, max_length=100)
    age: int = Field(ge=18)
    
@router.post("/users", status_code=201)
async def create_user(data: CreateUserRequest) -> UserResponse:
    ...

Python — FastAPI

from fastapi import APIRouter, HTTPException, status
from pydantic import BaseModel, EmailStr, Field

router = APIRouter(prefix="/users", tags=["users"])

class CreateUserRequest(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    email: EmailStr

class UserResponse(BaseModel):
    id: int
    name: str
    email: str

@router.post("", status_code=status.HTTP_201_CREATED, response_model=UserResponse)
async def create_user(data: CreateUserRequest, db: Session = Depends(get_db)):
    if await db.get_by_email(data.email):
        raise HTTPException(status.HTTP_409_CONFLICT, "Email already registered")
    user = await db.create_user(data)
    return UserResponse.model_validate(user)

@router.get("/{user_id}", response_model=UserResponse)
async def get_user(user_id: int, db: Session = Depends(get_db)):
    user = await db.get_user(user_id)
    if not user:
        raise HTTPException(status.HTTP_404_NOT_FOUND, "User not found")
    return UserResponse.model_validate(user)

Node.js — Express

const router = express.Router();

// POST /users
router.post('/', validateBody(createUserSchema), async (req, res, next) => {
  try {
    const existing = await User.findByEmail(req.body.email);
    if (existing) {
      return res.status(409).json({
        error: { code: 'CONFLICT', message: 'Email already registered' }
      });
    }
    const user = await User.create(req.body);
    res.status(201).location(`/users/${user.id}`).json(toUserResponse(user));
  } catch (err) {
    next(err);
  }
});

// GET /users/:id
router.get('/:id', async (req, res, next) => {
  try {
    const user = await User.findById(req.params.id);
    if (!user) {
      return res.status(404).json({
        error: { code: 'NOT_FOUND', message: 'User not found' }
      });
    }
    res.json(toUserResponse(user));
  } catch (err) {
    next(err);
  }
});

// Consistent error shape helper
function toErrorResponse(code, message, details = []) {
  return { error: { code, message, details } };
}