カテゴリ管理
バージョン別機能範囲のご案内
- 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": []）に転換されました。