docs/api.md

API 명세서 (v1)

Base URL

/api/v1

요약

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

공통 에러 응답 (예시)

{
  "success": false,
  "error": {
    "code": 400,
    "message": "Bad Request",
    "details": null
  }
}

인증 / Rate limiting

• 인증: 선택(예: JWT Authorization: Bearer ), 필요한 엔드포인트에 표기
• 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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "title":"새 게시글",
  "content":"내용",
  "image_url":"/uploads/sample.jpg",
  "prediction":"cat",
  "confidence":0.95
}

Response 201:

{"success": true, "id": 123}

Validation: title required, image_url optional, confidence 0.0-1.0

[PUT] 게시글 수정

PUT /api/v1/posts/{id} Request body (partial 허용):

{"title":"수정 제목","content":"수정 내용"}

Response 200: {"success": true}

[DELETE] 게시글 삭제

DELETE /api/v1/posts/{id} Response 200:

{"success": true, "message": "삭제 완료"}

---

4. 좋아요 / 추천

POST /api/v1/posts/{id}/like Response 200:

{"success": true, "likes": 12}

---

5. 통계 API (대시보드용)

GET /api/v1/stats/classes Query params (optional):

• start_date, end_date (ISO 8601) Response 200:

{"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)으로 문제 추적

---