Cursor rule

1---
2globs:
3  - "packages/hermes-api/app/api/**/*.py"
4---
5 
6# Hermes API - FastAPI Endpoints Rules
7 
8## Endpoint Structure
9 
10### File Organization
11- Endpoints in `app/api/v1/endpoints/`
12- One resource per file: `downloads.py`, `auth.py`
13- Router registration in `app/api/v1/router.py`
14- Shared dependencies in `app/api/dependencies.py`
15 
16### Router Definition
17```python
18from fastapi import APIRouter
19 
20router = APIRouter(tags=["downloads"])
21 
22@router.get("/list")
23async def list_downloads():
24    pass
25```
26 
27## Dependency Injection
28 
29### Common Dependencies
30```python
31from app.api.dependencies import get_current_user_from_token
32from app.db.session import get_database_session
33 
34@router.get("/profile")
35async def get_profile(
36    current_user: dict = Depends(get_current_user_from_token),
37    db: AsyncSession = Depends(get_database_session)
38):
39    return current_user
40```
41 
42- `get_database_session()` - Database session
43- `get_current_user_from_token()` - Authenticated user
44- `get_current_user_optional()` - Optional auth
45 
46## Request/Response Models
47 
48```python
49from pydantic import Field
50from app.models.pydantic.download import DownloadCreateRequest, DownloadResponse
51 
52@router.post("/", response_model=DownloadResponse, status_code=201)
53async def create_download(
54    request: DownloadCreateRequest,
55    current_user: dict = Depends(get_current_user_from_token),
56    db: AsyncSession = Depends(get_database_session)
57):
58    # Implementation
59    pass
60```
61 
62### Model Naming
63- `CreateRequest` - For creation
64- `UpdateRequest` - For updates
65- `Response` - For responses
66- `ListResponse` - For lists
67 
68## Error Handling
69 
70### HTTP Exceptions
71```python
72from fastapi import HTTPException, status
73 
74if not download:
75    raise HTTPException(
76        status_code=status.HTTP_404_NOT_FOUND,
77        detail=f"Download {download_id} not found"
78    )
79```
80 
81Common status codes:
82- `400 BAD_REQUEST` - Invalid input
83- `401 UNAUTHORIZED` - Auth required
84- `403 FORBIDDEN` - Permission denied
85- `404 NOT_FOUND` - Not found
86- `409 CONFLICT` - Duplicate
87- `422 UNPROCESSABLE_ENTITY` - Validation error (automatic)
88- `500 INTERNAL_SERVER_ERROR` - Server error
89 
90### Logging
91```python
92from app.core.logging import get_logger
93 
94logger = get_logger(__name__)
95 
96try:
97    # Operation
98    pass
99except Exception as e:
100    logger.error(
101        "Operation failed",
102        error=str(e),
103        error_type=type(e).__name__,
104        user_id=current_user["id"]
105    )
106    raise HTTPException(
107        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
108        detail="Operation failed"
109    )
110```
111 
112## Endpoint Patterns
113 
114### List
115```python
116@router.get("/", response_model=List[ItemResponse])
117async def list_items(
118    skip: int = Query(0, ge=0),
119    limit: int = Query(100, ge=1, le=100),
120    db: AsyncSession = Depends(get_database_session)
121):
122    repos = await get_repositories()
123    items = await repos["items"].get_all(skip=skip, limit=limit)
124    return items
125```
126 
127### Create
128```python
129@router.post("/", status_code=status.HTTP_201_CREATED, response_model=ItemResponse)
130async def create_item(
131    request: ItemCreateRequest,
132    current_user: dict = Depends(get_current_user_from_token),
133    db: AsyncSession = Depends(get_database_session)
134):
135    repos = await get_repositories()
136    item = await repos["items"].create({
137        **request.dict(),
138        "user_id": current_user["id"]
139    })
140    return item
141```
142 
143### Get
144```python
145@router.get("/{item_id}", response_model=ItemResponse)
146async def get_item(
147    item_id: str,
148    current_user: dict = Depends(get_current_user_from_token),
149    db: AsyncSession = Depends(get_database_session)
150):
151    repos = await get_repositories()
152    item = await repos["items"].get_by_id(item_id)
153    
154    if not item:
155        raise HTTPException(
156            status_code=status.HTTP_404_NOT_FOUND,
157            detail=f"Item {item_id} not found"
158        )
159    
160    if item.user_id != current_user["id"]:
161        raise HTTPException(
162            status_code=status.HTTP_403_FORBIDDEN,
163            detail="Not authorized"
164        )
165    
166    return item
167```
168 
169### Delete
170```python
171@router.delete("/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
172async def delete_item(
173    item_id: str,
174    current_user: dict = Depends(get_current_user_from_token),
175    db: AsyncSession = Depends(get_database_session)
176):
177    repos = await get_repositories()
178    item = await repos["items"].get_by_id(item_id)
179    
180    if not item:
181        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
182    
183    if item.user_id != current_user["id"]:
184        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN)
185    
186    await repos["items"].delete(item_id)
187```
188 
189## Background Tasks
190 
191```python
192from app.tasks.download_tasks import process_download
193 
194@router.post("/download")
195async def trigger_download(
196    request: DownloadRequest,
197    current_user: dict = Depends(get_current_user_from_token)
198):
199    task = process_download.delay(
200        url=request.url,
201        user_id=current_user["id"]
202    )
203    
204    return {"task_id": task.id, "status": "queued"}
205```
206 
207## OpenAPI Documentation
208 
209```python
210@router.get("/{item_id}", response_model=ItemResponse)
211async def get_item(item_id: str):
212    """
213    Get a single item by ID.
214    
215    Returns item details if found and user has access.
216    Raises 404 if item doesn't exist.
217    """
218    pass
219```
220 
221- Include docstrings for all endpoints
222- Use tags to group related endpoints
223- Document parameters and responses
224