ゆめうさAPIの強化版を公開！
YouTubeとTwitch、どちらも配信を見るなら身近なプラットフォームです。
でも開発者の立場に立つと、「両方の配信情報をまとめて扱いたい」と思ったとき、
APIの仕様の違いがすぐに壁になります。
強化版ゆめうさAPIは、
前作のゆめうさAPIにさらなる機能と安定性を追加し、
基本的にはWordPressや自作サイトからでも情報にアクセスできるように改良した
バックエンドです。
本記事では、詳しい実装には踏み込まず、
「どんなことを解決しているのか」をやさしく紹介します。
※ゆめうさAPIとは、画像右側の虹色の髪のVTuber(ゆめうさ)のサイトに実装されている、
「ゆめうさ友人帳」内の各VTuberさん達のうち、Twitchで配信している人の配信情報を、
ほぼリアルタイムで取得・通知するプラットフォーム連携・通知機能です。
※あくまでシステム上は、TwitchとYouTubeの情報を送信しています。
（まゆねこサーバー上で情報を取得し、APIで提供しています。）
なぜ作ったのか
配信者やファン向けのサービスを作るとき、
「YouTubeの配信開始」「Twitchの配信終了」「アーカイブが公開された」
といった情報を、プラットフォームごとに別々のAPIで取ってくるのは大変です。
データの形も更新のタイミングもバラバラで、
フロントエンド側が「プラットフォームごとの例外処理」に埋もれがちになります。
ゆめうさAPIは 、
「プラットフォームの違いはサーバー側で吸収して、クライアントには揃った形で渡す」
という考え方で設計されています。
主な機能・特徴
一つのAPIでYouTubeとTwitchを扱える
・ YouTube（動画・ライブ・アーカイブ）とTwitch（ライブ・VOD）の情報を、
共通のレスポンス形式で取得
・ チャンネル名・@ハンドル・IDなど、入力形式が違ってもチャンネルを特定
・ 非表示にしたいチャンネル（Muted）は、裏では監視しつつ公開APIからは除外
プラットフォームの「ズレ」を埋める工夫
APIをそのまま使うだけでは取れない情報や、タイミングが合わないデータがあります。
ゆめうさAPIでは、次のような工夫で「正確で揃ったデータ」を届けています。
1. あえて60秒待つ——正確さのための設計
TwitchはWebhookで「配信が始まった」とすぐ通知してくれますが、
あくまでそれは速報であって、まだTwitchのAPI上で情報が準備できておらず、
タイトルやカテゴリが欠けているなど、情報不足になることがよくあります。
ゆめうさAPIでは、Twitchからの速報データを受けとっても、すぐ詳細情報は取得せず、
60秒待ってから詳細情報を取得する設計を採用しています。
配信終了時も同様に、アーカイブの生成を待ってからデータを取りに行きます。
「速さ」より「確実に正しい情報を返す」ことを優先しています。
2. 消えたデータをスナップショットで救う
Twitchのアーカイブ（VOD）を後から取ると、
ライブ中に設定されていたゲーム名やタグなどが欠けていることがあります。
ゆめうさAPIは、ライブ配信中の情報をスナップショットとして保存し、
アーカイブ取得時に足りない情報をスナップショットから補完します。
さらに、TwitchAPIが直接返してくれない「配信終了時刻」も、
開始時刻と配信継続時間から自動で計算して、ゆめうさAPI側の情報として提供します。
3. 「取得中」を正直に伝える Pending ステータス
60秒待つ設計の裏側では、詳細情報がまだ揃っていない時間帯があります。
ここでエラーを返すのではなく、
`detail_status: “pending”`（情報取得中）というステータスを返します。
フロントエンドは「失敗」ではなく「準備中」として扱えるので、
ローディング表示やプレースホルダーで、待ち時間を自然に演出できます。
4. Redisで遅延ジョブを守る
60秒後に実行する処理は、本番環境ではRedisのキューで管理しています。
アプリが再起動しても、未処理のジョブが消えないようにするためです。
Redisがない環境(セルフホスト時など)では、メモリ上で動くフォールバックもありますが、
ゆめうさAPIシステムとしては、信頼性を重視した構成を推奨しています。
5. 識別子を賢く解釈する
ユーザーが入力するチャンネル指定は、プラットフォームごとに形式が違います。
YouTube: チャンネルID（`UC…`）、@ハンドル、チャンネル名
Twitch: 数値ID、ログイン名（英字）、表示名
ゆめうさAPIは、これらを優先順位付きで解釈し、
どの形式で入力されても、意図したチャンネルにつなげるように構成しています。
ワークスペースで「見える範囲」を分ける
データ本体（動画・VOD・配信状態）はサーバー内の共有プールに置き、
ワークスペースごとにOwn登録と購読で可視範囲を分けます。
各ユーザーはそれぞれ違ったread keyを持ち、認証後にデータを取得します
共有プール：各ユーザーが通知登録したチャンネルからの通知を１箇所にまとめている場所。
ワークスペース：各ユーザー毎の通知希望チャンネルやその状態を管理する場所。
Own登録：通知希望チャンネルを登録した人をOwnと言います。
購読：既に登録されているチャンネルを別の人が登録しようとすると、購読になります。
read key：各ワークスペースの利用とAPIアクセス時に必要な認証情報です。
旧システムとの違い
・自分が登録したチャンネル、購読したチャンネルだけがAPIに載ります。
・同じチャンネルの情報を複数のユーザーで共有できます。
・ユーザー認証やその他の認証機能の強化により安全に利用できるようになりました。
・このシステムは引き続き、一般公開はしていません。
利用希望があったユーザーにのみ提供しています。
「一つのAPIにまとめる」だけでなく、「誰に何を返すか」まで揃えるのが、
いまのゆめうさAPIの形です。
まとめ
ゆめうさAPIは、
YouTubeとTwitchの配信情報を一つの窓口にまとめるためのシステムです。
・プラットフォームごとのAPIの違いをサーバー側で吸収
・タイミングのズレや欠けたデータを、待機・スナップショット・計算で補完
・取得中の状態も含めて、フロントエンドに渡す情報を揃える
・読み取りはワークスペース単位の可視範囲と read key で保護
「複数の配信プラットフォームをまたぐサービス」を作るとき、
最初にぶつかる「仕様の壁」を、できるだけ開発者の手前で片付ける…
そんな役割を担っています。