docs/api-guides/QUICK_REFERENCE_PROJECTION.md

Projection List - Quick Reference

TL;DR

All list endpoints MUST support projection list for field selection.

Quick Implementation

1. Schema (Add to your request model)

projection_list: Optional[List[str]] = Field(
    None, 
    description="List of fields to include in response"
)

2. Service (Add projection logic)

async def list_items(
    filters: dict,
    skip: int = 0,
    limit: int = 100,
    projection_list: Optional[List[str]] = None  # Add this
):
    # Build projection
    projection_dict = None
    if projection_list:
        projection_dict = {field: 1 for field in projection_list}
        projection_dict["_id"] = 0
    
    # Use projection in query
    cursor = collection.find(query, projection_dict).skip(skip).limit(limit)
    docs = await cursor.to_list(length=limit)
    
    # Return raw dict if projection, model otherwise
    return docs if projection_list else [Model(**d) for d in docs]

3. Controller (Pass projection to service)

@router.post("/list")
async def list_items(payload: ListRequest):
    return await Service.list_items(
        filters=payload.filters,
        skip=payload.skip,
        limit=payload.limit,
        projection_list=payload.projection_list  # Pass this
    )

Usage Examples

Get specific fields only

curl -X POST /employees/list \
  -H "Content-Type: application/json" \
  -d '{
    "skip": 0,
    "limit": 10,
    "projection_list": ["user_id", "first_name", "email"]
  }'

Get all fields (omit projection)

curl -X POST /employees/list \
  -H "Content-Type: application/json" \
  -d '{
    "skip": 0,
    "limit": 10
  }'

Common Projections

Dropdown/Select

{"projection_list": ["id", "name"]}

List View

{"projection_list": ["id", "name", "status", "created_at"]}

Dashboard Widget

{"projection_list": ["id", "name", "count", "total"]}

Checklist

• Request schema has projection_list field
• Service accepts projection_list parameter
• Service builds MongoDB projection dict
• Service returns dict for projection, model otherwise
• Controller passes projection to service
• Endpoint uses POST method
• Tests cover projection scenarios

Full Documentation

• Standards: API_STANDARDS.md
• Implementation Guide: PROJECTION_LIST_IMPLEMENTATION.md