はじめに

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 型に加えて拡張型が定義されています。

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}

規約

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

認証

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

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

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

IP コントロール認証 を参照してディスプレイの認証を設定してください。「Pre-Shared Key」で認証をすると、認証レベル「private」の API と認証レベル「generic」の API を使用することができるようになります。

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 サービスリスト