docs/api.md

# API 명세서 (v1)

Base URL
```
/api/v1
```

요약
- 주요 리소스: /posts, /predict, /uploads, /stats
- 응답 포맷: JSON (HTML 페이지는 웹 라우트로 별도 제공)
- 필드 네이밍: snake_case
- 날짜/시간: ISO 8601 (예: 2026-04-28T12:34:56Z)

공통 에러 응답 (예시)
```json
{
  "success": false,
  "error": {
    "code": 400,
    "message": "Bad Request",
    "details": null
  }
}
```

인증 / Rate limiting
- 인증: 선택(예: JWT Authorization: Bearer <token>), 필요한 엔드포인트에 표기
- Rate limit: 예시 - 60 requests/min (문서화 권장)

모델 메타데이터(권장 응답 필드)
- model_name, model_version, inference_time_ms

---

## 1. 웹 페이지 라우팅 (HTML)
(웹 서버 템플릿용; API Base URL 적용 없음)
- GET / → 200 HTML (index.html)
- GET /board → 200 HTML (board.html)
- GET /posts/{post_id} → 200 HTML (post detail)

---

## 2. 이미지 분류 API (routers/predict.py)

### [POST] 이미지 분류
POST /api/v1/predict
Headers:
- Content-Type: multipart/form-data
Request (form-data):
- file: (required) image file, field name `file` (max 10MB, allowed: .jpg, .jpeg, .png)
Response 200:
```json
{
  "success": true,
  "filename": "cat.jpg",
  "predicted_class": "cat",
  "confidence": 0.9821,
  "top_k": [
    {"label":"cat","score":0.9821},
    {"label":"dog","score":0.0121}
  ],
  "model": {
    "name": "classifier",
    "version": "v1.0.0"
  },
  "inference_time_ms": 123
}
```
Errors:
- 400: missing file / invalid file type
- 413: payload too large
- 500: model inference failure

---

### [POST] 이미지 업로드 + 분류 + 게시글 자동 생성
POST /api/v1/predict/upload
Headers:
- Content-Type: multipart/form-data
Request (form-data):
- title: string (required)
- content: string (optional)
- image: file (required) field name `image`
Response 201:
```json
{
  "success": true,
  "post_id": 15,
  "prediction": "cat",
  "confidence": 0.98,
  "model": {"name":"classifier","version":"v1.0.0"}
}
```

---

### [GET] 모델 라벨 목록
GET /api/v1/predict/labels
Response 200:
```json
{
  "classes": ["cat","dog","car","person"]
}
```

---

## 3. 게시글 API (routers/post.py)

### [GET] 게시글 목록 (페이징/필터)
GET /api/v1/posts
Query params:
- page: int (default 1)
- size: int (default 10)
- category: string (optional)
Response 200:
```json
{
  "items": [
    {
      "id": 1,
      "title": "고양이 분류 성공",
      "prediction": "cat",
      "confidence": 0.98,
      "created_at": "2026-04-28T12:00:00Z"
    }
  ],
  "page": 1,
  "size": 10,
  "total": 34
}
```

### [GET] 게시글 상세
GET /api/v1/posts/{id}
Response 200:
```json
{
  "id": 1,
  "title": "고양이 분류 성공",
  "content": "테스트 글",
  "image_url": "/uploads/cat.jpg",
  "prediction": "cat",
  "confidence": 0.98,
  "created_at": "2026-04-28T12:00:00Z"
}
```
404: post not found

### [POST] 게시글 생성
POST /api/v1/posts
Headers:
- Content-Type: application/json
Request body:
```json
{
  "title":"새 게시글",
  "content":"내용",
  "image_url":"/uploads/sample.jpg",
  "prediction":"cat",
  "confidence":0.95
}
```
Response 201:
```json
{"success": true, "id": 123}
```
Validation: title required, image_url optional, confidence 0.0-1.0

### [PUT] 게시글 수정
PUT /api/v1/posts/{id}
Request body (partial 허용):
```json
{"title":"수정 제목","content":"수정 내용"}
```
Response 200: {"success": true}

### [DELETE] 게시글 삭제
DELETE /api/v1/posts/{id}
Response 200:
```json
{"success": true, "message": "삭제 완료"}
```

---

## 4. 좋아요 / 추천
POST /api/v1/posts/{id}/like
Response 200:
```json
{"success": true, "likes": 12}
```

---

## 5. 통계 API (대시보드용)
GET /api/v1/stats/classes
Query params (optional):
- start_date, end_date (ISO 8601)
Response 200:
```json
{"cat":34,"dog":20,"car":14}
```

---

## 데이터/응답 스키마 (schemas.py)

PostCreate
- title: string (required)
- content: string (optional)
- image_url: string (optional, 경로)
- prediction: string (optional)
- confidence: float (0.0 - 1.0, optional)

PostResponse
- id: int
- title: string
- content: string
- image_url: string
- prediction: string
- confidence: float
- created_at: datetime (ISO 8601)

PredictResponse
- success: bool
- filename: string
- predicted_class: string
- confidence: float
- top_k: [{label: string, score: float}]
- model: {name:string, version:string}
- inference_time_ms: int

ErrorResponse
- success: false
- error: {code:int, message:string, details:object|null}

---

## 구현/운영 권장사항
- 모든 API는 /api/v1/ 접두사를 사용해 버전 관리
- 요청/응답 예시는 OpenAPI(Swagger)로 작성해 자동 문서화 권장
- 파일 업로드는 저장소 용량, 확장자 검사, 악성 파일 검사 구현
- 민감한 파일 업로드는 인증/ACL 적용
- 모델 버전 관리 및 A/B 테스트 로그 남기기
- 자세한 로깅(요청 id, inference time, model version)으로 문제 추적

---