본문으로 건너뛰기

북마크 관리

북마크 관리 API v3 레퍼런스 바로가기
버전별 기능 범위 안내
  • v1: 북마크 관련 기능을 지원하지 않습니다.
  • v2: 북마크 목록 조회 기능만 제한적으로 지원합니다.
  • v3: 목록 조회 기능 고도화와 더불어 북마크 추가/수정/삭제 기능이 추가되었습니다.
  • 공통 인증: 모든 버전의 API는 쿼리 스트링 파라미터(?access_token=)를 통한 공통 인증 방식을 사용합니다. 에러 판정 기준에 대한 공통 명세는 API v3 마이그레이션 가이드의 핵심 변경 사항 섹션을 참고하세요.
v2 에러 응답 규격 (Laravel 프레임워크 스타일)

v2의 북마크 API 에러 처리는 HTTP 200 상태 코드와 내부에 { "error": 1 }을 반환하는 일반적인 VOD API와 다릅니다. 아래의 예시와 같이 실제 대응하는 HTTP 상태 코드와 구체적인 에러 객체({ message, errors }) 구조를 반환합니다.

  • 잘못된 upload_file_key 전달: HTTP 422 + { "message": "The given data was invalid.", "errors": {...} }
  • 존재하지 않는 client_user_id 전달: HTTP 404 + { "message": "Record not found" }

북마크 목록 조회 (업로드 파일 키 기준)​

  • 기존 (v1): 미지원
  • 기존 (v2): GET /vod/bookmarks
  • 변경 (v3): GET /media-contents/{upload_file_key}/bookmarks
변경 사항
  • 식별자 파라미터 위치 변경: v2에서 쿼리 파라미터로 전달하던 upload_file_key가 v3에서는 경로 파라미터 규격으로 변경되었습니다.
  • 응답 필드 추가: 고유 식별자(id)와 시간 정보(created_at, updated_at) 필드가 추가되었습니다.
요청 파라미터 및 응답 구조 상세

요청 쿼리 파라미터​

v2에서는 동일 엔드포인트에서 media_content_key로도 조회가 가능했으나, v3에서는 media_content_key를 경로 파라미터로 사용하는 별도 엔드포인트(/media-content-keys/{media_content_key}/bookmarks)가 신설되어 upload_file_key 기준 조회만 지원합니다.

  • v2: media_content_key, upload_file_key, client_user_id
  • v3: client_user_id

응답 구조 대조​

  • v2
{
  "data": [
    {
      "kind": 0,
      "label": "bookmark_title",
      "position": 1,
      "value": "bookmark_content"
    }
  ]
}
  • v3
{
  "data": [
    {
      "id": 1,
      "kind": 0,
      "label": "bookmark_title",
      "position": 120,
      "value": "bookmark_content",
      "created_at": "2026-02-27T06:34:22+00:00",
      "updated_at": "2026-02-28T06:34:22+00:00"
    }
  ]
}

북마크 목록 조회 (미디어 콘텐츠 키 기준)​

  • 기존 (v1/v2): 미지원 (v2는 상단 업로드 파일 키 기준 API의 쿼리 파라미터로 기능을 대체했습니다.)
  • 변경 (v3): GET /media-content-keys/{media_content_key}/bookmarks
신규 기능 안내

v3에 논리적으로 분리 신설된 엔드포인트입니다. 식별자인 media_content_key를 경로 파라미터로 사용하여 북마크 목록을 조회합니다.

요청 파라미터 및 응답 구조 상세

요청 쿼리 파라미터​

파라미터데이터 타입필수 여부설명
client_user_idString필수고객사 사용자 ID

응답 구조 명세​

응답 스펙은 북마크 목록 조회 (업로드 파일 키 기준)의 응답 구조와 완전히 동일합니다.

북마크 추가​

  • 기존 (v1/v2): 미지원
  • 변경 (v3): POST /media-contents/{upload_file_key}/bookmarks
요청 본문 및 응답 구조 상세

요청 본문​

필드데이터 타입필수 여부설명
positionInteger필수북마크를 지정할 위치 (sec)
valueString선택북마크 내용

응답 구조 명세​

{
  "data": ApiVodBookmark object,
  "status": "ok"
}

북마크 수정​

  • 기존 (v1/v2): 미지원
  • 변경 (v3): PUT /media-contents/{upload_file_key}/bookmarks/{bookmark_id}
요청 본문 및 응답 구조 상세

요청 본문​

필드데이터 타입필수 여부설명
valueString필수수정할 북마크 내용

응답 구조 명세​

{
  "data": ApiVodBookmark object,
  "status": "ok"
}

북마크 삭제​

  • 기존 (v1/v2): 미지원
  • 변경 (v3): DELETE /media-contents/{upload_file_key}/bookmarks/{bookmark_id}
응답 구조 상세

응답 구조 명세​

{
  "data": [],
  "status": "ok"
}