API 명세서 해석

일반 원칙

Base URL

• https://api.example.com/api/v1

인증 (Authentication)

• 모든 API 요청의 Authorization 헤더에 Bearer Token 형식의 JWT를 포함해야 합니다.
• Example: Authorization: Bearer {YOUR_JWT_TOKEN}

타임스탬프 (Timestamp)

• 모든 시간 관련 필드는 ISO 8601 UTC (Z-suffix) 형식을 따릅니다.
• Example: "2025-11-10T09:30:00Z"

공통 에러 응답 (Common Error Response)

• API 호출 실패 시, 모든 에러는 아래와 같은 통일된 JSON 형식으로 반환됩니다.

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested video does not exist."
  }
}

HTTP 상태 코드 (HTTP Status Codes)

코드 의미 설명

200 OK	성공	요청이 성공적으로 처리됨.
201 Created	생성됨	리소스가 성공적으로 생성됨. (향후 동기 API 추가 시 사용 가능)
202 Accepted	수락됨	비동기 작업 요청이 성공적으로 접수됨.
400 Bad Request	잘못된 요청	요청 파라미터가 유효하지 않음.
401 Unauthorized	인증 실패	유효한 JWT 토큰이 없거나 만료됨.
404 Not Found	리소스 없음	요청한 리소스를 찾을 수 없음.
409 Conflict	충돌	Idempotency-Key 중복 등 리소스 생성 충돌.
500 Internal Server Error	서버 오류	서버 내부에서 처리 중 오류 발생.

---

데이터 모델 (Data Models)

영상 상태 Enum (Video Status Enum)

상태 설명

PENDING	영상 생성 요청이 시스템에 접수되었으나, 아직 처리 대기 중인 상태.
PROCESSING	영상 생성이 시작되어 진행 중인 상태.
COMPLETED	영상 생성이 성공적으로 완료된 상태.
FAILED	영상 생성 중 오류가 발생하여 실패한 상태.

---

API 엔드포인트

📑 기사 (Article) API

1) 기사 목록 조회

• Endpoint: GET /articles
• Description: 커서 기반 페이지네이션을 사용하여 기사 목록을 조회합니다. next_cursor 값이 null이면 마지막 페이지입니다.
• Query Parameters:

파라미터 타입 설명 기본값

limit	integer	페이지당 개수	20
cursor	string	다음 페이지 조회를 위한 커서 값	null
keyword	string	검색어	null

• Success Response (200 OK):

{
  "next_cursor": "c_20251109180000_95", // mvp 미적용
  "total_estimate": 5230,                 // mvp 미적용
  "articles": [
    {
      "id": 101,
      "title": "...",
      "publisher": "...",
      "published_at": "2025-11-10T09:30:00Z",
      "url": "https://..."
    }
  ]
}

2) 기사 상세 조회

• Endpoint: GET /articles/{id}
• Description: 단일 기사의 상세 정보를 조회합니다.
• Success Response (200 OK): Article 객체 반환
• Error Response: 404 Not Found

 {
      "id": 101,
      "title": "...",
      "publisher": "...",
      "published_at": "2025-11-10T09:30:00Z",
      "url": "https://..."
}

---

🎬 영상 (Video) API

1) 영상 생성 요청

• Endpoint: POST /videos
• Description: 선택한 기사들로 비동기 영상 생성을 요청합니다.
• 현재는 비동기 처리만 지원하므로 202 Accepted를 반환합니다. 향후 빠른 동기 생성 API 추가 시에는 201 Created를 반환할 수 있습니다.
• Headers:

헤더 설명

Idempotency-Key

(권장) 멱등성을 보장하기 위한 고유 키(UUID 등). 동일한 Authorization과 Idempotency-Key 조합의 요청은 24시간 내에 중복으로 간주되어 첫 요청과 동일한 응답을 반환합니다.

• Request Body:

{
  "article_ids": [101, 102],
}

• Success Response (202 Accepted):

{
  "id": "1"
  "status": "PENDING",
  "message": "Video creation request has been accepted."
}

2) 내 영상 목록 조회

• Endpoint: GET /videos
• Query Parameters:

파라미터 타입 설명

status

string

필터링할 영상 상태 (e.g., COMPLETED)

• Success Response (200 OK): videos 배열 반환
• 영상 많아지면 페이징 처리 필요 (mvp 제외)

3) 특정 영상 상세 정보 조회

• Endpoint: GET /videos/{id}
• Description:
  • FAILED 상태의 영상도 정상적인 리소스로 간주되므로, HTTP 상태 코드는 항상 200 OK를 반환합니다.
  • thumbnail_url은 status가 PENDING, PROCESSING, FAILED일 경우 항상 기본 이미지 URL(https://cdn.example.com/thumbnails/default.jpg)을 반환하며, null이 아닙니다.
• Success Response (200 OK): Video 객체 반환

// Example for a COMPLETED video
{
  "id": "vid_27e12eab-77a8-45a7-96a1-255a6a68b7b2",
  "article_ids": [101, 102],
  "title": "정부, 전기차 보조금 정책 변경",
  "status": "COMPLETED",
  "requested_at": "2025-11-09T15:20:00Z",
  "completed_at": "2025-11-09T16:00:00Z",
  "thumbnail_url": "<https://cdn.example.com/thumbnails/27e12eab.jpg>",
  "video_url": "<https://cdn.example.com/videos/27e12eab.mp4>",
  "failure": null // status가 'FAILED' 일때 공통 에러 응답(링크) 객체가 할당됨, 나머지 상태에서는 null
}

---

실시간 상태 업데이트 (WebSocket)

폴링(Polling) 방식 대신 WebSocket을 통해 영상 상태 변경 이벤트를 실시간으로 수신해야 합니다.

연결 (Connection)

• Endpoint: wss://api.example.com/v1/stream
• Authentication: 연결 시 Authorization: Bearer {JWT} 헤더를 전달해야 합니다.

이벤트 (Events)

• 서버는 클라이언트로 아래와 같은 형식의 메시지를 전송합니다.
• 서버는 연결 유지를 위해 최소 30~60초마다 heartbeat 이벤트를 보낼 수 있습니다.

{
  "event_type": "video_status_update",
  "payload": {
    "id": "1",
    "status": "COMPLETED",
    "title": "삼성전자 3분기 실적 발표 요약",
    "thumbnail_url": "<https://cdn.example.com/thumbnails/d290f1ee.jpg>",
    "video_url": "<https://cdn.example.com/videos/d290f1ee.mp4>"
  }
}

event_type payload 설명

video_status_update	영상의 상태가 변경되었을 때 발생. 업데이트된 Video 객체 정보를 포함.
heartbeat	연결 유지를 위한 주기적 신호. payload는 null이거나 간단한 타임스탬프.
error	서버 측 에러 발생 시 전송. payload는 에러 객체.

테이블 articles

CREATE TABLE articles ( id SERIAL PRIMARY KEY, title TEXT NOT NULL, summary TEXT, content TEXT, source VARCHAR(255), url TEXT, published_at TIMESTAMP, saved_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP );