본문으로 건너뛰기

카테고리 관리

카테고리 관리 API v3 레퍼런스 바로가기
버전별 기능 범위 안내
  • v1: 카테고리 자체의 CRUD 기능을 지원합니다.
  • v2: 카테고리 자체의 CRUD 기능을 지원하지 않으며, 채널 연결 및 해제 기능만 제공합니다.
  • v3: 전체 카테고리 CRUD 및 채널 연결 기능을 표준 REST API 형태로 통합 제공합니다.
  • 공통 인증: 모든 버전의 API는 쿼리 스트링 파라미터(?access_token=)를 통한 공통 인증 방식을 사용합니다. 에러 판정 기준에 대한 공통 명세는 API v3 마이그레이션 가이드의 핵심 변경 사항 섹션을 참고하세요.

카테고리 목록 조회​

  • 기존 (v1): GET /media/category/index
  • 변경 (v3): GET /categories
변경 사항
  • 응답 데이터 구조 변경: 반환되는 데이터의 배열 위치가 기존 result.items[]에서 data[] 구조로 변경되었으며, 페이징 처리를 위한 pagination 객체가 추가되었습니다.
  • 필터 및 페이지네이션 파라미터 추가: v1에서는 order 파라미터만 지원했으나, v3에서는 parent_category_key, page, per_page 파라미터가 추가되었습니다.
요청 파라미터 및 응답 필드 상세 매핑

요청 쿼리 파라미터​

파라미터v1 지원 여부v3 지원 여부설명
order지원 (created_at/position/name과 asc/desc 조합, 기본값: name_asc)지원 (v1과 동일한 Enum 스펙 유지)정렬 기준
parent_category_key미지원지원상위 카테고리 기준 필터링
page미지원지원요청할 페이지 번호
per_page미지원지원페이지당 노출할 항목 수

응답 필드 매핑​

id, key, name, position, level 필드는 전 버전 공통으로 동일하게 유지됩니다.

필드v1 구조 (result.items[])v3 구조 (data[])참고
부모 식별자parent_id (최상위 카테고리인 경우 NULL)parent_id + parent_keyv3에서는 문자열 형태의 parent_key가 함께 반환됩니다.
콘텐츠 카운트count_of_media_contents-v3 응답 데이터 스펙에서 제거되었습니다.
신규 추가 필드-default, created_at, updated_at, children_exist, channels[]카테고리 기본 속성 및 연결된 채널 배열 정보가 추가되었습니다.

최상위 기본 카테고리 정의 명세​

최상위(Root) 레벨의 기본 카테고리는 다음과 같이 항상 고정된 메타데이터를 반환합니다.

{
    "name": "None",
    "level": 0,
    "parent_id": null
}

신규 카테고리 생성​

  • 기존 (v1): POST /media/category/create
  • 변경 (v3): POST /categories
변경 사항
  • 부모 카테고리 지정 방식 변경: 상위 카테고리 지정 파라미터가 정수형 식별자인 parent_id에서 문자열 식별자인 parent_category_key로 변경되었습니다.
  • 응답 데이터 명세 고도화: v1에서는 성공 시 결과 데이터 없이 성공 여부({ error, message })만 반환하여 생성된 카테고리의 고유 키를 알 수 없었으나, v3에서는 생성 완료 시 HTTP 201 Created 상태 코드와 함께 생성된 카테고리 객체 전체를 반환합니다.
요청 본문 및 응답 구조 상세

요청 본문​

필드데이터 타입 (v1)데이터 타입 (v3)필수 여부설명
nameStringString필수생성할 카테고리 명칭
parent_idInteger(사용 불가)선택상위 카테고리 고유 식별자
parent_category_key-String선택상위 카테고리 고유 식별자

응답 구조 대조​

  • v1: 성공 시 고유 Key 필드가 누락된 상태로 메시지만 반환합니다. 응답 메시지 내 철자 오류(sucessfully)가 존재합니다.
{ "error": 0, "message": "sucessfully" }
  • v3: 표준 데이터 구조를 반환합니다.
{ "data": ApiVodCategory object, "status": "ok" }

카테고리 정보 조회​

  • 기존 (v1/v2): 미지원 (단건 조회 엔드포인트 없음)
  • 변경 (v3): GET /categories/{category_key}
응답 구조 상세

응답 구조 명세​

응답 필드는 카테고리 목록 조회의 항목 스펙(id, key, name, parent_id, parent_key, level, default, position, created_at, updated_at, children_exist, channels[])과 동일합니다.

{ 
    "data": ApiVodCategory object
}

카테고리 수정​

  • 기존 (v1): POST /media/category/edit/{category_key}
  • 변경 (v3): PUT /categories/{category_key}
변경 사항
  • HTTP 메서드 전환: HTTP 메서드가 POST에서 PUT으로 변경되었습니다.
  • 반환 식별자 데이터 타입 변경: 수정 완료 후 반환되는 식별자 형태가 기존 정수형 result.id에서 문자열 고유 키 구조인 data.key로 변경되었습니다.
요청 상세 및 응답 구조 상세

요청 명세 및 제약 조건​

  • 요청 본문: 변경할 카테고리 명칭 파라미터인 name (필수) 항목은 v1과 v3가 동일합니다.
  • 비즈니스 제약 조건: 시스템 기본 카테고리("없음/None")는 수정할 수 없습니다. v1의 경우 해당 요청 실패 시 "default category is not edited." 오류 메시지를 반환합니다.

응답 구조 대조​

  • v1
{ "error": 0, "message": "...", "result": { "id": 123 } }
  • v3
{ "data": ApiVodCategory object, "status": "ok" }

카테고리 삭제​

  • 기존 (v1): POST /media/category/delete/{category_key}
  • 변경 (v3): DELETE /categories/{category_key}
변경 사항
  • HTTP 메서드 전환: HTTP 메서드가 POST에서 DELETE로 변경되었습니다.
  • 응답 본문 데이터 최소화: v1에서는 삭제된 대상을 result.id 형태로 반환했으나, v3에서는 완전히 삭제 처리되었음을 뜻하는 빈 배열 구조(data: [])를 반환합니다.

카테고리–채널 연결​

  • 기존 (v2): GET /vod/channel-mapping/{media_content_group}/attach/{media_package}
  • 변경 (v3): POST /categories/{category_key}/channels/{channel_key}/attach
변경 사항
  • HTTP 메서드 정상화: 상태를 변경(연결)하는 동작임에도 v2에서 GET 메서드를 사용하던 논리적 오류를 v3에서 POST 메서드로 정정했습니다.
  • 파라미터명 표준화: 리소스 인지성을 높이기 위해 URL 경로 파라미터명이 변경되었습니다.
    • media_content_group → category_key
    • media_package → channel_key
  • 응답 데이터 표준화: v2에서는 처리가 성공하면 텍스트 응답 구조인 "Successfully attach" 문자열을 그대로 반환했으나, v3에서는 데이터 가독성을 위해 매핑 처리가 완료된 카테고리 데이터 객체 구조({ "data": ApiVodCategory object, "status": "ok" })를 정형화하여 반환합니다.

카테고리–채널 연결 해제​

  • 기존 (v2): DELETE /vod/channel-mapping/{media_content_group}/detach/{media_package}
  • 변경 (v3): DELETE /categories/{category_key}/channels/{channel_key}/detach
변경 사항
  • 파라미터명 표준화: 카테고리-채널 연결 기능과 동일하게 경로 파라미터명이 기술 표준에 맞춰 변경되었습니다.
    • media_content_group → category_key
    • media_package → channel_key
  • 응답 데이터 타입 구조화: v2의 텍스트 응답인 "Successfully detach" 구조에서 v3는 빈 배열 구조("data": [])로 전환되었습니다.