Introduction

REST API Specifications

Protocol Specifications Overview

REST API uses JSON-RPC over HTTP. This document mainly explains the JSON data format of request/response for each API. REST API is categorized into services based on functionality. The list of defined services is listed at the bottom of this page. Service names are used as part of the REST API URL.

http://[Base URL]/[service name]

Note:

URLs with a trailing “/” (slash) after [service name] are not accepted.

Each service should be exclusive, and it should be clear which service an API can belong to. It should be easier for the user to search for an API, by searching only the list of APIs in a particular service. Each API belonging to a service should be called using that service’s URL.

Base URL

[IP]/sony

REST API URL Example for avControl services (IP: 192.168.0.1)

http://192.168.0.1/sony/avControl

Versioning

REST API specifications are managed with a version control system. Each API has its own version. Each version is represented as two numbers separated by a “.” (dot).

X.Y

X represents the major’s version. If any big change is made, this number is incremented. Here, a big change means that a protocol specification change affects definitions over services. Y represents the specification’s minor version. This number will be incremented when the definition of an API is changed. The API definition represents the format of JSON. For example, if a member is added in a request or response, the version must be incremented. Basically, every API should be defined from version 1.0. The client can call a specific version’s API by setting the version in a request. This version information can be used only to distinguish an API call capability. If a client side application wants to change its behavior based on the server application’s/product’s generation, the client side application should use another API to retrieve the generation. (Ex. getInterfaceInformation on the system service.)

REST API Types

In REST API, extended types are defined in addition to JSON types.

JSON-RPC and Extensions/Restrictions

JSON-RPC is used with some restriction and extension. JSON-RPC is a simple and light communication protocol.

JSON-RPC Request Example

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

JSON-RPC Response Example

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

BRAVIA Professional Display has adapted some extensions and restrictions to keep APIs simple and easy-to-use.

• Extensions
  • If a request succeeds, “error” is ignored in the response. However, if a request fails, “result” is skipped.
  • The “error” member must be an array and is defined as [error_code, error_message]. “error_code” is an integer, “error_message” is a string. (Common error codes and messages are explained here. API specific error codes are explained on each API definition.)
  • “error_message” is just for debugging purposes. The client application must not use this to change its behavior, otherwise a different message might be set with same ““error_code”.
  • “version” must be set in the request. By setting the version, the client side is not affected when the server’s behavior is changed. The version can be set as two numbers separated by a dot (ex. “1.0”). The versioning system is explained above.
• Restrictions
  • Null valued parameters must be regarded as absent in the request/response, unless otherwise mentioned in each API specification.
  • “params”/”result” must be an array type of fixed length. (The length is defined on each API specification.)
  • “id” is an integer and “0” must not be used. “0” is used as a special number system. The id can be set to “1” - “2147483647” (0x00000001 - 0x7FFFFFFF).

REST API Request Example

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

REST API Response Example (Success Case)

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

REST API Response Example (Failure Case)

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

Conventions

A document’s internal description conventions are described below.

Authentication

Currently following authentication levels are defined.

Authentication levels are hierarchical with “private” being highest in the hierarchy. An API is accessible by a client application with the same or higher access level in the hierarchy. This means if the authentication with level “private” is accepted by user for a client application, then the APIs categorized in lower level (i.e. “generic” ) are also available for the client application. On the contrary, if a lower level authentication is accepted by user for a client application, then the APIs categorized in higher level are not available for the client application.

REST API server should follow this level described in each API section.

Please visit IP Control Authentication to setup authentication on BRAVIA Professional Display. If you authenticated the client application with the “Pre-Shared Key” method, the APIs categorized in “private” and the APIs categorized in “generic” are available for the client application.

REST-API HTTP Request Example (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

See Wake-on-LAN.

API Service List