Create a New FastAPI API Endpoint

Pattern

All API routers use FastAPI's APIRouter with prefix and tags, and are registered in myca_main.py.

Steps

API Endpoint Creation Progress:
- [ ] Step 1: Create router file
- [ ] Step 2: Register in myca_main.py
- [ ] Step 3: Update API catalog
- [ ] Step 4: Test endpoints

Step 1: Create the router file

Create mycosoft_mas/core/routers/your_api.py:

python
1"""Your API - Brief description of these endpoints."""
2
3from fastapi import APIRouter, HTTPException, Depends
4from pydantic import BaseModel
5from typing import Any, Dict, List, Optional
6
7
8router = APIRouter(prefix="/api/your-domain", tags=["your-domain"])
9
10
11class YourRequest(BaseModel):
12    """Request model."""
13    field: str
14    optional_field: Optional[str] = None
15
16
17class YourResponse(BaseModel):
18    """Response model."""
19    status: str
20    data: Dict[str, Any]
21
22
23@router.get("/health")
24async def health():
25    """Health check for this API domain."""
26    return {"status": "healthy", "service": "your-domain"}
27
28
29@router.post("/action", response_model=YourResponse)
30async def perform_action(request: YourRequest):
31    """Perform an action."""
32    try:
33        # Implementation here
34        result = {"processed": request.field}
35        return YourResponse(status="success", data=result)
36    except Exception as e:
37        raise HTTPException(status_code=500, detail=str(e))
38
39
40@router.get("/items")
41async def list_items():
42    """List items."""
43    return {"items": [], "count": 0}

Step 2: Register in myca_main.py

Edit mycosoft_mas/core/myca_main.py:

python
1# Add import
2from mycosoft_mas.core.routers.your_api import router as your_router
3
4# Add router inclusion (in the router registration section)
5app.include_router(your_router, tags=["your-domain"])

Step 3: Update API catalog

Update docs/API_CATALOG_FEB04_2026.md with new endpoints:

markdown
1### Your Domain API
2| Endpoint | Method | Description |
3|----------|--------|-------------|
4| /api/your-domain/health | GET | Health check |
5| /api/your-domain/action | POST | Perform action |
6| /api/your-domain/items | GET | List items |

Step 4: Test endpoints

bash
1# Health check
2curl http://192.168.0.188:8001/api/your-domain/health
3
4# Test action
5curl -X POST http://192.168.0.188:8001/api/your-domain/action \
6  -H "Content-Type: application/json" \
7  -d '{"field": "test"}'

Key Rules

• Always include a /health endpoint per router
• Use Pydantic models for request/response validation
• Include proper error handling with HTTPException
• Use async endpoints
• Add tags for OpenAPI documentation grouping
• Update API_CATALOG after adding endpoints