카테고리
버전별 기능 범위 안내
- 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_key | v3에서는 문자열 형태의 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) | 필수 여부 | 설명 |
|---|---|---|---|---|
name | String | String | 필수 | 생성할 카테고리 명칭 |
parent_id | Integer | (사용 불가) | 선택 | 상위 카테고리 고유 식별자 |
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_keymedia_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_keymedia_package→channel_key
- 응답 데이터 타입 구조화: v2의 텍스트 응답인
"Successfully detach"구조에서 v3는 빈 배열 구조("data": [])로 전환되었습니다.