REST API

Ritsuki Goto edited this page Apr 2, 2017 · 27 revisions

Chinachu WUI REST API Document

Document Contents:

Requests & Responses

Base URL

全てのREST APIは次のbase URLから始まります:

https?://host:port/api/

通信の内容を暗号化し、保護するには wuiTlsKeyPath, wuiTlsKeyPath を設定してTLSを有効化してください

Request and Response Formats

基本的にリクエストにはQueryStringを、レスポンスはJSONを使用します。

/api/resource.json?query=string

このようになります。レスポンスフォーマットを指定するために、拡張子は必須です。

Authentication

wuiUsers が設定されている場合、何の変哲もないBASIC認証が有効になります。

Response Status Codes & Errors

Chinachu REST API では以下のようなステータスコードを返すようになっています:

  • 200 OK: リクエストは成功し、正常に処理された。
  • 202 ACCEPTED: リクエストは受理された。処理は続行される。
  • 400 BAD REQUEST: 不正なリクエスト。
  • 401 UNAUTHORIZED: 認証が必要です。
  • 403 FORBIDDEN: リクエストの実行が拒否された。
  • 404 NOT FOUND: リクエストされたAPIまたはリソースは見つからなかった。
  • 405 METHOD NOT ALLOWED: 許可されていないメソッドでリクエストした。
  • 409 CONFLICT: リクエストに関して何らかの衝突が発生した。
  • 410 GONE: あるはずのリソースが、行方不明になった。録画実行中に出力ファイルが消失した場合などに発生。
  • 415 UNSUPPORTED MEDIA TYPE: 指定されたレスポンスフォーマットが有効でない場合に発生。
  • 500 INTERNAL SERVER ERROR: 内部エラーが発生した。バグと思われる場合は報告してください。
  • 501 NOT IMPLEMENTED: 実装または有効になっていないリソースまたは機能をリクエストした。
  • 503 SERVICE UNAVAILABLE: 過負荷状態またはメンテナンス状態であるためリクエストが続行できなかった。

Resources

/scheduler

スケジューラ

URI: /scheduler.format

Formats: json, txt

Methods

  • GET: Schedulerの実行結果
  • PUT: Schedulerを実行

/scheduler/force

強制的にスケジューラを実行(EPGデータ再取得)

URI: /scheduler/force.format

Formats: json

Methods PUT

/rules

予約ルール

  • ルールの条件が空の場合は400エラーが返ります。 (POST)

URI: /rules.format

Formats: json

Methods

  • GET: 自動予約ルール一覧
  • POST: 新規ルール追加

/rules/:ruleNum

自動予約ルール

  • ルールが見つからなかった場合は404エラーが返ります。
  • ルールの条件が空の場合は400エラーが返ります。 (PUT)

URI: /rules/:ruleNum.format

Formats: json

Methods

  • GET: ルールデータ
  • PUT: ルール編集
  • DELETE: ルール削除

/rules/:ruleNum/:action

自動予約ルール設定

URI: /rules/:ruleNum/:action.format

Formats: json

Methods PUT

Parameter

  • enable: 有効化
  • disable: 無効化

/program/:programId

プログラム情報

  • プログラムが見つからなかった場合は404エラーが返ります。
  • 既に予約されていた場合は409エラーが返ります。 (PUT)

URI: /program/:programId.format

Formats: json

Methods

  • GET: プログラムデータ
  • PUT: 手動予約

/schedule

Schedule (番組表) 取得

URI: /schedule.format

Formats: json

Methods

  • GET: 番組表 (チャンネル配列)
  • HEAD: GET時のHeaderが取得できます。Content-Lengthを取得できます。

/schedule/:channelId

チャンネル別番組表取得

URI: /schedule/:channelId.format

Formats: json

Methods

  • GET: 番組表 (指定チャンネル)

/schedule/programs

全プログラムデータ取得

URI: /schedule/programs.format

Formats: json

Methods

  • GET: プログラムデータ配列

/schedule/broadcasting

全放送中プログラムデータ取得

URI: /schedule/broadcasting.format

Formats: json

Methods

  • GET: プログラムデータ配列

/schedule/:channelId/programs

チャンネルの全プログラムデータ取得

URI: /schedule/:channelId/programs.format

Formats: json

Methods

  • GET: プログラムデータ配列

/schedule/:channelId/broadcasting

チャンネルの全放送中プログラムデータ取得

URI: /schedule/:channelId/broadcasting.format

Formats: json

Methods

  • GET: プログラムデータ配列

/reserves

予約済プログラムリスト取得

URI: /reserves.format

Formats: json

Methods

  • GET: 予約済リスト

/reserves/:programId

予約済プログラム情報

URI: /reserves/:programId.format

Formats: json

Methods

  • GET: プログラムデータ
  • DELETE: 手動予約解除

/recording

録画中一覧取得

URI: /recording.format

Formats: json

Methods

  • GET: 録画中リスト

/recording/:programId

録画中プログラム情報

URI: /recording/:programId.format

Formats: json

Methods

  • GET: プログラムデータ
  • DELETE: 録画中止

/recording/:programId/preview

録画中プログラムプレビュー画像取得

  • ffmpegを利用します。3秒以内に画像が生成されない場合はkillされます。
  • wuiPreviewer が有効になっていないと403エラーが返ります。
  • スクランブルがかかっている場合は409エラーが返ります。
  • 録画中のファイルが消失している場合は410エラーが返ります。
  • パラメータにtxtを指定するとbase64が返ります。

URI: /recording/:programId/preview.format

Formats: png, jpg, txt

Methods: GET

Parameters

画像パラメータ参照

/recording/:programId/watch

録画中プログラムストリーミング再生

  • wuiStreamer が有効になっていないと403エラーが返ります。
  • スクランブルがかかっている場合は409エラーが返ります。
  • 録画中のファイルが消失している場合は410エラーが返ります。

URI: /recording/:programId/watch.format

Formats

  • xspf: XSPFプレイリスト
  • m2ts, webm: トランスコード・ストリーミング再生

Methods: GET

Parameters

動画パラメータ参照

/recorded

録画済プログラムリスト

URI: /recorded.format

Formats: json

Methods

  • GET: 録画済リスト
  • PUT: 録画済リストクリーンアップ

/recorded/:programId

録画済プログラム情報

URI: /recorded/:programId.format

Formats: json

Methods

  • GET: プログラムデータ
  • DELETE: プログラムデータ削除

/recorded/:programId/file

録画済プログラムファイル

URI: /recorded/:programId/file.format

Formats: json, m2ts

Methods

  • GET: ファイル/ファイル情報
  • DELETE: ファイル削除

/recorded/:programId/preview

録画済プログラムプレビュー画像取得

  • ffmpegを利用します。3秒以内に画像が生成されない場合はkillされます。
  • wuiPreviewer が有効になっていないと403エラーが返ります。
  • スクランブルがかかっている場合は409エラーが返ります。
  • 録画中のファイルが消失している場合は410エラーが返ります。
  • パラメータにtxtを指定するとbase64が返ります。

URI: /recorded/:programId/preview.format

Formats: png, jpg, txt

Methods: GET

Parameters

画像パラメータ参照

/recorded/:programId/watch

録画済プログラムストリーミング再生

  • wuiStreamer が有効になっていないと403エラーが返ります。
  • スクランブルがかかっている場合は409エラーが返ります。
  • 録画中のファイルが消失している場合は410エラーが返ります。

注意: このAPIで手に入るmp4ファイルは長さデータが入っていない不完全なものです。

URI: /recorded/:programId/watch.format

Formats

  • xspf: XSPFプレイリスト
  • mp4, m2ts, webm: トランスコード・ストリーミング再生

Methods: GET

Parameters: 動画パラメータ参照

/channel/:programId/logo

チャンネルロゴ取得

URI: /channel/:programId/logo.format

Formats: png

Methods: GET

/channel/:programId/watch

リアルタイムストリーミング再生

URI: /channel/:programId/watch.format

Formats: xspf, m2ts, webm

Methods: GET

Parameters: 動画パラメータ参照

/config

コンフィグ

URI: /config.format

Formats: json

Methods:

  • GET: 取得
  • PUT: 保存

/log/:name

ログ取得 nameにはファイル名が入ります(wui, operator, scheduler)

URI: /log/:name.format

Formats: json

Methods: GET

/log/:name/stream

ログストリーミング取得 nameにはファイル名が入ります(wui, operator, scheduler)

URI: /log/:name/stream.format

Formats: json

Methods: GET

/status

サーバー情報取得

URI: /status.format

Formats: json

Methods: GET

/storage

ストレージ情報取得

URI: /storage.format

Formats: json

Methods: GET

Parameters & About

Image Parameter

key default memo
pos 7 プレビュー位置(秒数)
width 320 横幅をピクセル単位で指定
height 180 縦幅
size 320x180 横x縦をピクセル単位で指定 (優先)

注意: recording(録画中)はposの指定が出来ません。

Video Parameter

  • xspf: XSPFプレイリスト
key default memo
ext m2ts m2ts, f4v, flv, webm, asfから指定
prefix

これに合わせて以下のパラメーターを指定できます。

  • m2ts, webm, mp4: トランスコード・ストリーミング再生
key default memo
ss (無指定) 開始位置を秒数で指定。指定しないとライブ再生。
t (無指定) 秒数を指定するとその長さだけ変換。
f (自動) コンテナフォーマット。 mpegts, flv, asf, webm
c:v (自動) 動画コーデック。 copy, libvpx, flv, libx264, wmv2
c:a (自動) 音声コーデック。 copy, libvorbis, libfdk_aac, wmav2
b:v (無指定) 動画ビットレート
b:a (無指定) 音声ビットレート
s (無指定) 映像サイズ(例:1280x720)
r (無指定) 映像フレームレート(例:24)

注意: ffmpegが対応しているコーデックとフォーマットのみ利用できます

ヒント: m2tsではデフォルト(パラメーター無指定)でリクエストした場合 ffmpegを使用しないパススルー再生が可能です

About

この文書は 2017/04/02 現在最新コミットである Chinachu γ f1a8254 に準拠しています。