はじめに

Estimated reading time: 3 minutes

REST API の仕様

プロトコルの概要

REST API は HTTP 上で JSON-RPC を使用します。 このドキュメントでは、主に各 API のリクエスト/レスポンスの JSON データフォーマットについて説明します。 REST API は機能に基づいてサービスに分類されます。定義されているサービスのリストはこのページの下部に一覧表示しています。 サービス名は REST API URL の一部として使用されます。

http://[Base URL]/[サービス名]

Note:

[サービス名]の後に “/” (スラッシュ) が付いている URL は受け付けられません。

サービスはそれぞれ独立しており、API がどのサービスに属しているか明確である必要があります。 特定のサービス内を検索することで、API を検索することが容易になります。 サービスに属している各 API は、そのサービスの URL を使用して呼び出す必要があります。

Base URL

[IP]/sony

avControl サービスの REST API URL の例 (IP:192.168.0.1)

http://192.168.0.1/sony/avControl

バージョン管理について

REST API 仕様はバージョン管理システムで管理されています。 各 API には固有のバージョンがあります。 各バージョンは、”.” (ドット) で区切られた 2 つの数字として表されます。

X.Y

X はメジャーバージョンを表します。大きな変更があった場合、この数値が増えます。 ここで言う大きな変更とは、プロトコル仕様変更がサービス上の定義に影響を与えることを意味します。 Y は仕様のマイナーバージョンを表します。 この数は、API の定義が変更されたときに増加します。 API 定義は JSON の形式を表します。 たとえば、リクエストまたはレスポンスにメンバーが追加された場合は、バージョンを増やす必要があります。 基本的に、すべての API はバージョン 1.0 から定義します。 クライアントはリクエストにバージョンを設定することで特定のバージョンの API を呼び出すことができます。 このバージョン情報は、API 呼び出し機能を区別するためにのみ使用します。 クライアント側のアプリケーションがサーバーアプリケーションの製品およびバージョンに基づいて動作の変更を行う場合は、 バージョンを取得するために別の API を使用します。(例:system サービスの getInterfaceInformation)

REST API の種類

REST API では、JSON 型に加えて拡張型が定義されています。

種類 説明
boolean 真偽値が格納されます。
boolean-array 複数の true または false 値が配列に格納されています。
integer -2147483648 から 2147483647 までの整数が格納されています。
integer-array 複数の整数が配列に格納されています。
double -2.2250738585072014e-308 から 1.7976931348623157e + 308 までの範囲の浮動小数点数型が格納されています。
double-array 複数の浮動小数点数型が配列に格納されます。
string 文字列値 各 API 仕様で特に明記されていない限り、文字列は UTF-8 でエンコードされています。
string-array 複数の文字列型データが配列に格納されています。

JSON-RPC の拡張機能と制限

JSON-RPC は拡張機能といくつかの制限事項があります。 JSON-RPC はシンプルで軽量な通信プロトコルです。

JSON-RPC リクエスト 例

{"method": "echo", "params": ["Hello REST API"], "id": 1}

JSON-RPC レスポンス 例

{"result": ["Hello REST API"], "error": null, "id": 1}

ディスプレイには、API をシンプルで使いやすいものにするための拡張機能と制限事項があります。

  • 拡張機能
    • リクエストが成功した場合、レスポンスでは ”error” は無視されます。ただし、リクエストが失敗すると、”result” はスキップされます。
    • “error” メンバは配列でなければならず、[error_code、error_message]として定義されています。 “error_code” は整数、”error_message” は文字列です。 (一般的なエラーコードとメッセージは ここで説明します。API 固有のエラーコードは各 API 定義で説明します。)
    • “error_message” はデバッグ用です。 クライアントアプリケーションはこれを使用して動作を変更してはいけません。 別のメッセージに同じ “error_code” が設定される可能性があるためです。
    • リクエストには “version” を設定する必要があります。”version” を設定することで、サーバーの動作が変更されてもクライアント側は影響を受けません。”version” は、ドットで区切られた 2 つの数字として設定できます(例:「1.0」)。バージョン管理については上で説明しています。
  • 制限事項
    • 各 API 仕様書で特に言及されていない限り、NULL 値は無効なパラメーターと見なされます。
    • “params” / “result” は固定長の配列型でなければなりません。 (長さは各 API 仕様で定義されています。)
    • “id” には整数を指定し、「0」は使用できません。 「0」は特別な番号体系で使用されます。 idは「1」 - 「2147483647」(0x00000001 - 0x7FFFFFFF)に設定できます。

REST API リクエスト 例

{"method": "getMyName", "params": [{"key": 1116}], "id": 2, "version": "1.0"}

REST API レスポンス 例 (成功)

{"result": [{"name": "Alice"}], "id": 2}

REST API レスポンス 例 (失敗)

{"error": [401, "Unauthorized"], "id": 2}

規約

文書の内部記述規約は以下の通りです。

Multiplicity 1 : 1回
? : 0または1回
* : 0回以上
Default デフォルトは、特定のパラメーターが欠損している場合にデータ受信側が送信側から送信したと見なす必要がある値です。
Date 時刻フォーマットとして、ISO 8601 を使用しています。
Country 国名コードとして、ISO 3166 alpha2 と追加のコードを使用しています。

認証

現在、以下の認証レベルが定義されています。

認証レベル 基準
private 認証が必要です。 個人情報にあたらない情報(個人の特定に使用可能な情報)ではなく、デバイス ID やデバイスのユーザーによって異なる可能性のある情報を提供する API。
generic 認証が必要です。 デバイスを制御したり、デバイスのステータスを変更したりする API。
none 認証は必要ありません。 上記の基準に一致しない API。

認証レベルは階層的で、「private」が最も高い認証レベルです。 API は、同一階層以上の認証レベルを持つクライアントアプリケーションからアクセスできます。 例えば、クライアントアプリケーションに対して認証レベル「private」の認証がユーザーによって承認された場合、 より低いレベルに分類された (すなわち「generic」) API も利用可能です。 逆に、クライアントアプリケーションに対して低いレベルの認証がユーザーによって承認された場合、高レベルに分類された API は使用できません。

REST API サーバーは、各 API セクションに記載されているこのレベルに従う必要があります。

IP コントロール認証 を参照してディスプレイの認証を設定してください。

REST-API HTTP リクエスト例 (Pre-Shared Key: “1234”)

POST /sony/system HTTP/1.1
Host: 192.168.0.1
Accept: */*
Cache-Control: no-cache
Connection: close
Content-Type: application/json; charset=UTF-8
Pragma: no-cache
X-Auth-PSK: 1234
Content-Length: 70

{"method": "getPowerStatus", "params": [], "id": 50, "version": "1.0"}

Wake-on-LAN

Wake-on-LAN を参照してください。

API サービスリスト

サービス 説明
guide サーバー上でサポートされているサービスのリストを取得するための API を提供するサービス
appControl アプリケーションの起動と、それに付随する特定のアプリケーションに関連する操作を処理する API 群を扱うサービス
audio 音量、効果音などのオーディオ機能に関する API 群を扱うサービス
avContent AV コンテンツ自体の操作とデバイスの入出力の全般的な制御を扱うサービス
encryption 暗号化処理に関連する API 群を扱うサービス
system 基本的なデバイス機能に関連する API 群を扱うサービス
videoScreen ビデオ画面機能に関連する API 群を扱うサービス
Last modified: 25 Dec 2019