API Development Skill

Purpose

Guide API development workflow for the career_ios_backend FastAPI project, ensuring all console.html APIs are properly tested and functional.

Automatic Activation

This skill is AUTOMATICALLY activated when user mentions:

✅ "develop API" / "API 開發"
✅ "create endpoint" / "創建端點"
✅ "test API" / "測試 API"
✅ "console.html"
✅ "Swagger UI"
✅ "FastAPI route"

Development Flow (Prototype Speed-First)

Standard Workflow

1. Write Feature Code (AI-Assisted)
   ↓ 70% time
2. Manual Test API (Swagger UI or Console)
   ↓ Quick verification
3. Write Integration Test (Verify API works)
   ↓ 20% time
4. ruff check --fix (Auto-fix formatting)
   ↓ Auto
5. Commit (Pre-commit hooks)
   ↓ ~5s
6. Push → CI runs Integration Tests
   ↓ ~2 min

Time Allocation

Development: 70% of time
Testing: 20% of time
Fixing/Refactoring: 10% of time

Philosophy: Prototype phase prioritizes speed over perfection. Functional validation comes before quality optimization.

Testing Requirements

Integration Tests (Mandatory)

CRITICAL: All

console.html

APIs MUST have integration tests.

bash

# Daily development: Run integration tests only
poetry run pytest tests/integration/ -v

# Full test suite (optional during development)
poetry run pytest tests/ -v

# Test specific API
poetry run pytest tests/integration/test_auth_api.py -v

Current Test Coverage

Status (2025-12-25):

✅ 106+ integration tests covering 35+ endpoints
✅ All major features tested:
- Authentication API (
```
test_auth_api.py
```
  )
- Client Management (
```
test_clients_api.py
```
  )
- Sessions/Consultations (
```
test_sessions_api.py
```
  )
- Case Management (
```
test_cases_api.py
```
  )
- Report Generation (
```
test_reports_api.py
```
  )
- RAG Features (
```
test_rag_*.py
```
  )

Requirements by Endpoint

Every API endpoint needs:

At least 1 happy path test
- Test successful request/response
- Verify expected data structure
- Check status codes
Authentication test (if protected)
- Use
```
auth_headers
```
  fixture
- Verify 401 for unauthenticated requests
Console integration (if used in console.html)
- Verify endpoint works from console
- Test actual user workflows

Console API Verification

All Console.html APIs Must Be Tested

Checklist:

bash

# Verify test coverage
poetry run pytest tests/integration/ -v | grep -E "(test_.*_api\.py|PASSED|FAILED)"

# Current coverage (106+ tests):
✅ Authentication (login, token refresh)
✅ Client Management (CRUD, search, code generation)
✅ Session Management (CRUD, transcripts, reflections)
✅ Case Management (CRUD, timeline)
✅ Report Generation (consultation reports)
✅ RAG Features (upload, embed, search, evaluate)

When Adding New Console Feature

TDD Flow for Console APIs:

1. Design API behavior
   ↓
2. Write integration test FIRST
   ↓ (test in tests/integration/)
3. Run test → RED (fails)
   ↓
4. Implement API endpoint
   ↓
5. Run test → GREEN (passes)
   ↓
6. Update console.html to use API
   ↓
7. Manual test in browser console

IMPORTANT: Test before console integration to catch bugs early.

API Structure (FastAPI)

Project Layout

app/
├── api/
│   ├── auth.py           # Authentication endpoints
│   ├── clients.py        # Client management
│   ├── sessions.py       # Session/consultation
│   ├── cases.py          # Case management
│   └── <feature>.py      # New feature routes
├── models/
│   ├── user.py           # SQLAlchemy models
│   ├── client.py
│   └── <feature>.py      # New feature models
├── schemas/
│   ├── client.py         # Pydantic schemas (request/response)
│   └── <feature>.py
├── services/              # Business logic (optional)
│   └── <feature>_service.py
└── main.py               # App initialization, router registration

Adding New API Endpoint

Step-by-Step:

Create route file (if new feature)

python

# app/api/my_feature.py
from fastapi import APIRouter, Depends

router = APIRouter(prefix="/api/v1/my-feature", tags=["my-feature"])

@router.get("/")
async def list_items():
    return {"items": []}

Define schemas (Pydantic)

python

# app/schemas/my_feature.py
from pydantic import BaseModel

class ItemCreate(BaseModel):
    name: str
    description: str

class ItemResponse(BaseModel):
    id: int
    name: str

Register router in

main.py

python

from app.api import my_feature

app.include_router(my_feature.router)

Write integration test FIRST (TDD)

python

# tests/integration/test_my_feature_api.py
@pytest.mark.asyncio
async def test_list_items(auth_headers):
    async with AsyncClient(app=app, base_url="http://test") as client:
        response = await client.get(
            "/api/v1/my-feature/",
            headers=auth_headers
        )
    assert response.status_code == 200

Manual Testing Tools

Swagger UI (OpenAPI Docs)

bash

# Start development server
poetry run uvicorn app.main:app --reload

# Open Swagger UI
http://localhost:8000/docs

# Features:
- Interactive API testing
- Auto-generated from FastAPI
- Try out endpoints directly
- See request/response schemas

Console.html Testing

bash

# 1. Start backend
poetry run uvicorn app.main:app --reload

# 2. Open console.html in browser
open console.html

# 3. Test workflows:
- Login
- Create client
- Add session
- Generate report
- etc.

httpx Manual Testing

python

# Quick test script (for complex scenarios)
import httpx
import asyncio

async def test_api():
    async with httpx.AsyncClient(base_url="http://localhost:8000") as client:
        # Login
        response = await client.post("/api/v1/auth/login", json={
            "username": "testuser",
            "password": "testpass"
        })
        token = response.json()["access_token"]

        # Test endpoint
        response = await client.get(
            "/api/v1/clients/",
            headers={"Authorization": f"Bearer {token}"}
        )
        print(response.json())

asyncio.run(test_api())

Authentication Patterns

Protected Endpoints

Most endpoints require authentication:

python

from app.core.security import get_current_user

@router.get("/protected")
async def protected_route(current_user = Depends(get_current_user)):
    return {"user": current_user.username}

Testing Authenticated Endpoints

Use

auth_headers

fixture:

python

@pytest.mark.asyncio
async def test_protected_endpoint(auth_headers):
    async with AsyncClient(app=app, base_url="http://test") as client:
        response = await client.get(
            "/api/v1/protected",
            headers=auth_headers  # Provides valid JWT token
        )
    assert response.status_code == 200

Authentication Test Pattern

python

# Test unauthenticated access (should fail)
@pytest.mark.asyncio
async def test_endpoint_requires_auth():
    async with AsyncClient(app=app, base_url="http://test") as client:
        response = await client.get("/api/v1/protected")
    assert response.status_code == 401  # Unauthorized

Database Considerations

Test Database

Integration tests use in-memory SQLite
Fixtures handle setup/teardown automatically
See
```
tests/conftest.py
```
for database fixtures

Database Patterns

python

from app.db.session import get_db
from sqlalchemy.orm import Session

@router.post("/clients")
async def create_client(
    client_data: ClientCreate,
    db: Session = Depends(get_db)
):
    # Use db session for database operations
    new_client = Client(**client_data.dict())
    db.add(new_client)
    db.commit()
    db.refresh(new_client)
    return new_client

Quality Standards (Prototype Phase)

Must Do ✅

Integration tests for all console.html APIs
Follow existing API patterns (check similar endpoints)
Use Pydantic schemas for request/response validation
Proper HTTP status codes:
- 200: Success
- 201: Created
- 400: Bad Request
- 401: Unauthorized
- 404: Not Found
- 500: Server Error

Nice-to-Have (Optional) ⚠️

Complete type hints
Edge case tests
Performance optimization
Comprehensive error messages

Don't Do ❌

100% test coverage (overkill for prototype)
Excessive mocking
Over-engineering

Remember: Prototype phase prioritizes functional validation over perfection.

Testing Commands Reference

bash

# Run all integration tests
poetry run pytest tests/integration/ -v

# Run specific test file
poetry run pytest tests/integration/test_clients_api.py -v

# Run specific test
poetry run pytest tests/integration/test_clients_api.py::test_create_client -v

# Run tests with coverage report (optional)
poetry run pytest tests/integration/ --cov=app --cov-report=html

# Run tests matching pattern
poetry run pytest -k "client" -v

Common Patterns

CRUD Operations

python

# CREATE
@router.post("/", response_model=ItemResponse, status_code=201)
async def create_item(item: ItemCreate, db: Session = Depends(get_db)):
    ...

# READ (list)
@router.get("/", response_model=List[ItemResponse])
async def list_items(db: Session = Depends(get_db)):
    ...

# READ (single)
@router.get("/{item_id}", response_model=ItemResponse)
async def get_item(item_id: int, db: Session = Depends(get_db)):
    ...

# UPDATE
@router.put("/{item_id}", response_model=ItemResponse)
async def update_item(item_id: int, item: ItemUpdate, db: Session = Depends(get_db)):
    ...

# DELETE
@router.delete("/{item_id}", status_code=204)
async def delete_item(item_id: int, db: Session = Depends(get_db)):
    ...

Error Handling

python

from fastapi import HTTPException

@router.get("/{item_id}")
async def get_item(item_id: int, db: Session = Depends(get_db)):
    item = db.query(Item).filter(Item.id == item_id).first()
    if not item:
        raise HTTPException(status_code=404, detail="Item not found")
    return item

Integration with TDD Workflow

API development follows TDD for critical features:

tdd-workflow skill activates:
  ↓
1. RED: Write integration test (fails)
   → tests/integration/test_<feature>_api.py
  ↓
2. GREEN: Implement API endpoint (passes)
   → app/api/<feature>.py
  ↓
3. REFACTOR: Code review and quality check
  ↓
4. git-workflow skill: Commit and push

Reference: See

tdd-workflow

skill for detailed TDD process.

Troubleshooting

"Test database not initialized"

bash

# Check conftest.py has database fixtures
# Ensure test uses proper fixtures
@pytest.mark.asyncio
async def test_endpoint(db_session):  # Use db fixture
    ...

"Import errors in tests"

bash

# Ensure PYTHONPATH includes project root
# Run from project root directory
cd /path/to/career_ios_backend
poetry run pytest tests/integration/ -v

"API endpoint not found (404)"

bash

# Verify router is registered in main.py
# Check route prefix and path
# Start server and check Swagger UI: /docs

Related Skills

tdd-workflow - Test-first development process
quality-standards - Code quality requirements
git-workflow - Git commit and push workflow

Skill Version: v1.0 Last Updated: 2025-12-25 Project: career_ios_backend (Prototype Phase)

api-development

NPX Install

Tags

SKILL.md Content

API Development Skill

Purpose

Automatic Activation

Development Flow (Prototype Speed-First)

Standard Workflow

Time Allocation

Testing Requirements

Integration Tests (Mandatory)

Current Test Coverage

Requirements by Endpoint

Console API Verification

All Console.html APIs Must Be Tested

When Adding New Console Feature

API Structure (FastAPI)

Project Layout

Adding New API Endpoint

Manual Testing Tools

Swagger UI (OpenAPI Docs)

Console.html Testing

httpx Manual Testing

Authentication Patterns

Protected Endpoints

Testing Authenticated Endpoints

Authentication Test Pattern

Database Considerations

Test Database

Database Patterns

Quality Standards (Prototype Phase)

Must Do ✅

Nice-to-Have (Optional) ⚠️

Don't Do ❌

Testing Commands Reference

Common Patterns

CRUD Operations

Error Handling

Integration with TDD Workflow

Troubleshooting

"Test database not initialized"

"Import errors in tests"

"API endpoint not found (404)"

Related Skills