Category Management

Notice

This document is a machine-translated draft and is currently undergoing review. Some content may be inaccurate or differ from the original Korean version. For the most precise information, refer to the Korean documentation.

Go to Category Management API v3 Reference→

Feature scope by version

• v1: Supports CRUD functionality for the category itself.
• v2: Does not support CRUD functionality for the category itself; only provides channel attach/detach functionality.
• v3: Provides full category CRUD and channel attach functionality in a unified, standard REST API format.
• Common authentication: All API versions use a common authentication method via a query string parameter (?access_token=). For the common specification on error determination criteria, refer to the Core changes section in the API v3 migration guide.

---

Retrieve category list

• Existing (v1): GET /media/category/index
• Changed (v3): GET /categories

Changes

• Response data structure change: The array position in the returned data has changed from the existing result.items[] to a data[] structure, and a pagination object has been added for pagination handling.
• Added filter and pagination parameters: v1 only supported the order parameter, but v3 adds the parent_category_key, page, and per_page parameters.

Detailed mapping of request parameters and response fields

Request query parameters

Parameter	Supported in v1	Supported in v3	Description
order	Supported (combination of created_at/position/name and asc/desc, default: name_asc)	Supported (maintains the same Enum spec as v1)	Sort criteria
parent_category_key	Not supported	Supported	Filter by parent category
page	Not supported	Supported	Page number to request
per_page	Not supported	Supported	Number of items to display per page

Response field mapping

The id, key, name, position, and level fields remain the same across all versions.

Field	v1 structure (result.items[])	v3 structure (data[])	Notes
Parent identifier	parent_id (NULL for top-level categories)	parent_id + parent_key	In v3, a string-form parent_key is also returned.
Content count	count_of_media_contents	-	Removed from the v3 response data spec.
Newly added fields	-	default, created_at, updated_at, children_exist, channels[]	Basic category properties and an array of linked channels have been added.

Top-level default category definition spec

The default category at the top (Root) level always returns fixed metadata as follows.

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

---

Create a new category

• Existing (v1): POST /media/category/create
• Changed (v3): POST /categories

Changes

• Parent category assignment method change: The parameter for specifying the parent category has changed from the integer identifier parent_id to the string identifier parent_category_key.
• Enhanced response data specification: In v1, only a success indicator ({ error, message }) was returned on success with no result data, making it impossible to know the unique key of the created category. In v3, upon successful creation, the full created category object is returned along with an HTTP 201 Created status code.

Details of the request body and response structure

Request body

Field	Data type (v1)	Data type (v3)	Required	Description
name	String	String	Required	Name of the category to create
parent_id	Integer	(Not available)	Optional	Unique identifier of the parent category
parent_category_key	-	String	Optional	Unique identifier of the parent category

Response structure comparison

• v1: Returns only a message with the unique Key field missing on success. There is a typo (sucessfully) in the response message.

{ "error": 0, "message": "sucessfully" }

• v3: Returns a standard data structure.

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

---

Retrieve category information

• Existing (v1/v2): Not supported (no single-item retrieval endpoint)
• Changed (v3): GET /categories/{category_key}

Details of the response structure

Response structure specification

The response fields are identical to the field spec (id, key, name, parent_id, parent_key, level, default, position, created_at, updated_at, children_exist, channels[]) in Retrieve category list.

{ 
    "data": ApiVodCategory object
}

---

Edit a category

• Existing (v1): POST /media/category/edit/{category_key}
• Changed (v3): PUT /categories/{category_key}

Changes

• HTTP method transition: The HTTP method has changed from POST to PUT.
• Returned identifier data type change: The identifier form returned after editing has changed from the existing integer result.id to the string unique key structure data.key.

Details of the request and response structure

Request specification and constraints

• Request body: The name parameter (required) for the new category name is the same in v1 and v3.
• Business constraint: The system default category ("None") cannot be edited. In v1, if this request fails, the error message "default category is not edited." is returned.

Response structure comparison

• v1

{ "error": 0, "message": "...", "result": { "id": 123 } }

• v3

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

---

Delete a category

• Existing (v1): POST /media/category/delete/{category_key}
• Changed (v3): DELETE /categories/{category_key}

Changes

• HTTP method transition: The HTTP method has changed from POST to DELETE.
• Minimized response body data: In v1, the deleted target was returned in the form of result.id, but in v3, an empty array structure (data: []) is returned to indicate that the deletion has been fully processed.

---

Category-channel attach

• Existing (v2): GET /vod/channel-mapping/{media_content_group}/attach/{media_package}
• Changed (v3): POST /categories/{category_key}/channels/{channel_key}/attach

Changes

• HTTP method normalization: Even though this action changes state (attaching), v2 used the GET method, which was a logical error. This has been corrected to the POST method in v3.
• Parameter name standardization: The URL path parameter names have been changed to improve resource recognizability.
  • media_content_group → category_key
  • media_package → channel_key
• Response data standardization: In v2, upon successful processing, the text response structure "Successfully attach" string was returned as is, but in v3, for data readability, a standardized category data object structure ({ "data": ApiVodCategory object, "status": "ok" }) indicating that the mapping process is complete is returned.

---

Category-channel detach

• Existing (v2): DELETE /vod/channel-mapping/{media_content_group}/detach/{media_package}
• Changed (v3): DELETE /categories/{category_key}/channels/{channel_key}/detach

Changes

• Parameter name standardization: As with the category-channel attach feature, the path parameter names have been changed to align with technical standards.
  • media_content_group → category_key
  • media_package → channel_key
• Response data type structuring: The v2 text response structure "Successfully detach" has been converted to an empty array structure ("data": []) in v3.