hesp.live APIのレスポンス内容がドキュメントに記載されていないものがあったので調べてみる

2022.03.17

リアルタイムストリーミングを提供するサービスであるhesp.liveですが、APIファーストでプロダクトが作られており、 現時点ではhesp.liveからストリーミング配信をする操作は全てAPIが提供されています。

Channelに関するAPIが提供されており、各APIのメソッドのリファレンスには説明、どういうリクエストを送ればいいのか、レスポンス結果の情報が記載されています。 しかもページ上から実行できたりもします(認証は必要)。

RESPONSESの項目のところにhttpのステータスコードのリストがあって、各リストをクリックすると中身が見れるようになっています。

上記は create-channelAPI のレスポンスです。

400エラーのレスポンスも開いてみます。

ん? objectとだけ書かれていて、200の時のような項目が入ってませんでした。

他の200が返ってくるAPIメソッドも確認してみると、

Get channels

create-channelAPI のレスポンスみたいに項目が表示されていませんでした。

書き忘れているだけなんでしょうか? そもそもレスポンス自体空っぽだから書いていないのでしょうか。

とりあえず全て実行して調べてみましょう。

Channel APIのレスポンス確認

APIリファレンスのページから直接実行した結果を見ていきます

Create channel

200系

実際に実行した結果、上記の結果が返ってきました。ドキュメントのRESPONSESに書かれている内容と違いますね。

まとめると以下のようになります。

object
channelId string
metadata object
metadata.name string
ingestConfig object
ingestConfig.abr string
ingestConfig.fps integer
ingestConfig.aspectRatio string
ingestConfig.preset string
ingestType string
streamKey string
region string
rtmpPushUrl string

400系

messageもしくはerrorという項目で返ってくるパターンがありました。

リクエストパラメータに不備があるとerrorが返ってきていましたね。

認証エラーの場合はmessageでした。

まとめると、

エラーコードが400
object
error string
エラーコードが400以外
object
message string

Start channel

ドキュメントの記載

200系

204 No Content です。

400系

Create channelの400系 と同じ

Stop channel

ドキュメントの記載

200系

204 No Content です。

400系

Create channelの400系 と同じ

Update channel

ドキュメントの記載

200系

なぜかHEADERSの記載がドキュメントになく、ページ上から実行できなかったのでクライアントPCからcurlで実行しました、。

204 No Content です。

400系

Create channelの400系 と同じ

Get channels

ドキュメントの記載

200系

アカウントに存在するチャンネルの一覧が返ってきます。

まとめると以下のようになります。

array
object
channelId string
metadata object
metadata.name string
metadata.customization object
metadata.customization.posterImg string
metadata.customization.logo string
metadata.customization.posterImg string
metadata.customization.colors object
metadata.customization.colors.secondary string
metadata.customization.colors.tertiary string
metadata.customization.colors.primary object
metadata.customization.autoplay boolean
metadata.customization.announcement string
mode string
ingestConfig object
ingestConfig.abr string
ingestConfig.fps integer
ingestConfig.aspectRatio string
ingestConfig.preset string
ingestType string
streamKey string
region string
rtmpPushUrl string
status object
status.code string
status.message string

400系

Create channelの400系 と同じ

Get channel status

ドキュメントの記載

200系

object
code string
message string

400系

Create channelの400系 と同じ

Delete channel

ドキュメントの記載

200系

204 No Content です。

400系

Create channelの400系 と同じ

最後に

現在提供されているAPI全て実行し、レスポンスボディを確認してみました。

ドキュメントの記述が足りない箇所があるので、これらをフィードバックしておこうかと思います。