ドキュメント一覧

オープン API

このページの内容

アドレスと形式
認証
閲覧トークンで使える API
デバイス
ライブ映像
セキュリティ上の注意

Rerinku View には公開の HTTP API があり、Web ページ、サーバー側のプログラム、アプリから直接呼び出せます。Web ページでは、認証・シグナリング・再接続をすべて処理してくれる Web SDK をおすすめします。このページでは API そのものについて説明します。ほかの言語を使う場合や、クライアントを自分で実装する場合に向いています。

アドレスと形式

ベースアドレスは Rerinku View のアドレスそのものです。LAN のアドレス（例：http://192.168.1.10:8080）か、クイック接続をオンにしている場合はクイック接続のアドレスです。設定 → 開発者 ページに、使えるアドレスが表示されます。API はすべて /api/v1/ の下にあります。
成功レスポンスは一律に data で包まれます：{ "data": ... }。バイナリとメディアのレスポンス（JPEG、SDP）は包まれません。
エラーレスポンスは一律に { "error": { "message": "...", "code": "..." } } です。HTTP ステータスコードで処理してください。区別が必要なエラー（認証、ライブストリームのシグナリング）には、機械が読める code が付きます。
リクエストボディに余分なフィールドは許されません。フィールドを 1 つでも余計に送ると 400 が返ります。
時刻はすべて RFC 3339 です。

認証

リクエストヘッダーにトークンを付けます。

Authorization: Bearer <トークン>

トークン	入手方法	できること
読み取り専用の閲覧トークン	コンソールの設定 → 開発者で作成します。作成できるのはコンソールだけです	下の表にあるいくつかの API だけを呼び出せます。公開の Web ページに書いて構いません
フル権限のトークン	`POST /api/v1/auth/bind`（モバイルアプリと同じように紐付け）	その紐付けに対応するフル権限

すべてのトークンは 設定 → 開発者 → 許可済みのアプリ（GET /api/v1/clients）に一覧され、いつでも取り消せます（DELETE /api/v1/clients/{id}）。取り消し後のリクエストは 401 になり、code は invalid_token です。

クロスオリジンのルール

どのサイトからでもクロスオリジンで呼び出せます。アクセスパスワードの設定も、オリジンの登録も不要です（CORS はすべてのオリジンを許可し、Allow-Credentials は送りません）。唯一の厳格なルールは、ほかのサイトからのリクエストにはトークンが必要ということです。そうでなければ、訪問者が開いた任意の Web ページが、その人のブラウザーを使って LAN 内の Rerinku View を操作できてしまいます。

ほかのサイトからのリクエスト	結果
`GET /api/v1/auth/info`	通常どおり。トークンは不要
`POST /api/v1/auth/bind`	Rerinku View にアクセスパスワードが設定されている場合：通常どおり（パスワードは bind が検証）。設定されていない場合：`403`、`code` は `cross_site_bind`
それ以外の `/api/v1/*`	有効なトークンがあれば通常どおり。なければ `401`、`code` は `authentication_required`

サーバー側のプログラムとネイティブアプリは Origin リクエストヘッダーを送らないので、このルールの対象外です。これらにトークンが必要かどうかは Rerinku View の待ち受けアドレスで決まります。ローカルのループバックだけで待ち受けている場合は不要で、LAN のアドレスで待ち受けている場合（既定）は必要です。

紐付けでフル権限のトークンを取得する

POST /api/v1/auth/bind
Content-Type: application/json

{ "password": "", "name": "店舗ダッシュボード", "platform": "sdk", "device_id": "dash-0001", "app_version": "1.0" }

{ "data": { "access_token": "<トークン>", "token_type": "Bearer" } }

password：Rerinku View のアクセスパスワード。設定していなければ空文字列を渡します。
device_id：自分で生成して長期間保存しておくインストール ID（8〜64 文字の英字、数字、-）。同じ ID で再び紐付けてもトークンが新しくなるだけで、許可が 1 件増えることはありません。
パスワードが間違っていると 401（invalid_password）、試行が多すぎると 429（too_many_attempts）が返ります。

閲覧トークンで使える API

API	説明
`GET /api/v1/devices`	デバイスの一覧。閲覧トークンで取得できるのはマスク処理されたフィールドで、アドレス、MAC、シリアル番号、ハードウェア ID、録画と PTZ の設定は含まれません
`GET /api/v1/devices/{id}/streams`	デバイスのストリーム一覧
`GET /api/v1/devices/{id}/thumbnail`	直近のフレームのサムネイル（JPEG）
`GET /api/v1/devices/{id}/runtime`	デバイスの現在の稼働状態。応答できるのは Rerinku View SDK で接続したデバイスだけです
`POST /api/v1/devices/{id}/live`、`POST /api/v1/devices/{id}/streams/{stream}/live`	ライブ映像の取得（WebRTC）
`GET /api/v1/ice-servers`	ライブ映像用の STUN/TURN の設定

それ以外の API は、閲覧トークンに対してすべて 403 を返し、code は insufficient_scope です。フル権限のトークンで使える API はもっと多くあります。Rerinku View リポジトリの docs/API.md を参照してください。

デバイス

GET /api/v1/devices

{
  "data": [
    {
      "id": 3,
      "sn": "0123456789ABCDEF",
      "name": "玄関",
      "protocol": "onvif",
      "group": "1階",
      "online": true,
      "streaming": false,
      "stream_kind": "webrtc",
      "video_codec": "H265",
      "has_thumbnail": true,
      "streams": [
        {
          "id": "main",
          "name": "メインストリーム",
          "default": false,
          "tracks": [{ "kind": "video", "codec": "H265" }]
        },
        {
          "id": "sub",
          "name": "サブストリーム",
          "default": true,
          "tracks": [{ "kind": "video", "codec": "H264" }]
        }
      ]
    }
  ]
}

stream_kind が unsupported の場合、ブラウザーではこのデバイスの映像を再生できません。
streams はデバイスの各ストリームです。default: true のものが、ストリームを指定しないときに再生されます。
Rerinku View SDK で接続したデバイスには ext も付きます。デバイスが自分で通知した静的な情報（SoC、CPU、メモリ、センサー……）です。

GET /api/v1/devices/{id}/runtime は、デバイスの現在の状態を返します。

{
  "data": {
    "supported": true,
    "online": true,
    "at": 1793000000000,
    "values": { "tempC": 63.6, "cpuPct": 11.2 }
  }
}

プラットフォームは毎回その場でデバイスに問い合わせますが、同じデバイスについては 2 秒以内なら結果を使い回します。これより速くポーリングしないでください。

ライブ映像

ライブ映像は 1 回きりの SDP 交換で、WHEP と同じ方式です。

GET /api/v1/ice-servers で STUN/TURN の設定を取得し、それを使って RTCPeerConnection を作成します（TURN の認証情報には期限があるので、接続のたびに取得します）。
受信専用（recvonly）の映像と音声のトランシーバーを追加して offer を生成し、ICE の収集が終わるのを待ちます。
offer をリクエストボディとして POST し、answer を受け取ります。

POST /api/v1/devices/{id}/streams/{stream}/live
Content-Type: application/sdp
Authorization: Bearer <トークン>

<SDP offer の本文>

成功すると 201 が返り、Content-Type: application/sdp で、レスポンスボディは SDP answer の本文です。/streams/{stream} を付けない場合は、既定のストリームを再生します。

ステータスコード	意味	推奨される対応
`404`	デバイスまたはストリームが存在しない	再試行しない
`409`	デバイスがオフライン（`code`：`device_offline`）	間隔を空けて再試行する。たとえば 15 秒ごとに 1 回
`422`	offer に問題がある、またはこの接続方式ではストリームを選べない	再試行しない
`408`、`504`	シグナリングのタイムアウト、デバイスがストリーム開始に応答しない	再試行してよい
`502`、`503`	デバイス側またはサービスが一時的に利用できない	バックオフして再試行する

接続が切れたら、同じアドレスでもう一度交換するだけです。Web SDK の再接続の方針は、この表のとおりに実装されています。

セキュリティ上の注意

公開の Web ページには Rerinku View のアドレスが書かれます。閲覧トークンが制限するのはそのトークンを付けたリクエストだけです。その Rerinku View にアクセスパスワードが設定されていなければ、アドレスを知っている人はコンソールを直接開けます（curl などのツールでも、ブラウザーの同一オリジンのリクエストを偽装できます）。閲覧トークンの制限ではこうした人を防げず、クイック接続のアドレスそのものが鍵と同じ意味を持ちます。公開デモに使う Rerinku View には、アクセスパスワードを設定するか、デモモード（DEMO_MODE）をオンにして、誰もが閲覧だけでき変更はできないようにしてください。また、クイック接続を使っている場合、/api/v1/ice-servers はこのノードの TURN 認証情報（24 時間有効）を返すので、公開すると、リレーを使うために持ち出されるおそれがあります。