REST API Basic Structure and Specifications

In the REST API, APIs are categorized by function, such as power control, volume adjustment, and input switching. In addition, function names are included in corresponding endpoint URLs. Request and response data specifications are also defined, enabling selective implementation of only required controls.

Available API Services

Example for URL

The Base URL consists of an IP address or hostname, plus /sony.​

[IP address] or [Host name]/sony

Service APIs can be accessed using the following URL structure.​

http://[IP address] or [Host name]/sony/[service name]

http://[IP address] or [Host name]/sony/[service name]

• A URL with a slash (/) at the end of the service name is invalid.
• Each service is independent. APIs are called using their corresponding service URLs.

Example for guide services (IP: 192.168.0.1)

http://192.168.0.1/sony/guide

The REST API is version-managed. Two types of versions are defined: the version specific to each API and the overall REST API version. These indicate the REST API version (generation version) and API-specific versions supported by the display.

How to Find the REST API Version Your Display Supports

{
"method": "getSystemInformation",
"id": 33,
"params": [],
"version": "1.0"
}

{
"method": "getSystemInformation",
"id": 33,
"params": [],
"version": "1.0"
}

{
"result": [{
"product": "TV",
"region": "",
"language": "eng",
"model": "FW-85BZ35P",
"serial": "1000001",
"macAddr": "12:34:56:78:9A:BC",
"name": "BRAVIA",
"generation": "6.5.0",
"area": "ZZZ",
"cid": "01234567890123456789012345678901"
}],
"id": 33
}

{
"result": [{
"product": "TV",
"region": "",
"language": "eng",
"model": "FW-85BZ35P",
"serial": "1000001",
"macAddr": "12:34:56:78:9A:BC",
"name": "BRAVIA",
"generation": "6.5.0",
"area": "ZZZ",
"cid": "01234567890123456789012345678901"
}],
"id": 33
}

The REST API defines its own extended format in addition to the standard JSON format. The API also has certain limitations.

JSON-RPC Data Types

Extensions

Limitations

Example for JSON-RPC

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

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

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

The Pre-shared key authentication system is managed through a hierarchy of three authentication levels.

Clients can access APIs at their authentication level or below. For example, a client with private-level authentication can also access generic and none-level APIs. However, a client with only generic-level authentication cannot access private-level APIs.

The monitor controls access based on the authentication level defined for each API.

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"}

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"}

The encryption system is a built-in feature provided with BRAVIA Professional Displays and is available through the encryption API, which encrypts and decrypts string parameters using standard 2048/1024-bit RSA (RFC 3447) and 128-bit AES-CBC (RFC 3602) algorithms to ensure that communication of those parameters is secure.

Encryption flow

1.Send Flow

The encryption system uses a hybrid method combining RSA public keys and AES symmetric keys. Sensitive data is encrypted with the AES symmetric key. RSA public keys are used to securely share the symmetric key between clients and the monitor.

Encrypted Send Flow Diagram

• Preparation
  The monitor creates an RSA key pair. The client creates an AES key and encrypts it with the RSA public key.
• Send
  The client encrypts sensitive data with the AES key and sends it to the monitor along with the encrypted AES key.
• Receive
  The monitor uses the RSA private key to decrypt the symmetric key. It then uses the decrypted symmetric key to decrypt the data.

2.Receive Flow

Encryption works the same way when sending data from the monitor to the client. After prior key preparation (RSA key pair generation, AES key generation), encrypted data and the encrypted AES key are communicated. Even if the communication is intercepted, it cannot be decrypted by a third party.

Encrypted Receive Flow Diagram

3.”getPublicKey” Definition

The getPublicKey method is a common API in the encryption system. Other APIs that send or retrieve encrypted parameters have an encKey element and at least one encrypted data element. If an API has multiple encrypted elements, a shared encKey must be included in params.

Example for JSON Send

JSON

{
    "method":"sendSecretData",
    "params":[
        {
            "secretData1":"G9KgQDustrxplKFcy9fnVQ==",
            "secretData2":"At2gQDgst6xplKFcy9fnVQ==",
            "encKey":"hCkxUu4WydqDwrlq+PsSSxBaIVbPFNeCU7XYgBC9bVmXvcTORXMdY5FeSr3LYu9WywFbh1WwTBW/S+xTPHZQXhQMUsWEFQwUSldm5xK8vhOcdzGe8kdrixAL6zL9qx6rioR95gF50FO1RRVS7jdsabPvHK5gXZHM9B2h24QKON1FeTkYVGKcf8J3JJp9gEWeNYG2bfMSvnS9qrn2bLXgAX71vwEz7Btm/+qmX7/nsrL5QGBdbgxUlK7q5JzZxOdDuh592lfdEoMIgFR144XAnhfqyCcuZLJ/60VjOpREQ17vTj6+NNVrSOIq4eHnBlB7SfFWM/CBa+rCFmYAzmm3VQ=="
        }
    ],
    "id":1,
    "version":"1.0"
}
{
    "result":[],
    "id":1
}

{
    "method":"sendSecretData",
    "params":[
        {
            "secretData1":"G9KgQDustrxplKFcy9fnVQ==",
            "secretData2":"At2gQDgst6xplKFcy9fnVQ==",
            "encKey":"hCkxUu4WydqDwrlq+PsSSxBaIVbPFNeCU7XYgBC9bVmXvcTORXMdY5FeSr3LYu9WywFbh1WwTBW/S+xTPHZQXhQMUsWEFQwUSldm5xK8vhOcdzGe8kdrixAL6zL9qx6rioR95gF50FO1RRVS7jdsabPvHK5gXZHM9B2h24QKON1FeTkYVGKcf8J3JJp9gEWeNYG2bfMSvnS9qrn2bLXgAX71vwEz7Btm/+qmX7/nsrL5QGBdbgxUlK7q5JzZxOdDuh592lfdEoMIgFR144XAnhfqyCcuZLJ/60VjOpREQ17vTj6+NNVrSOIq4eHnBlB7SfFWM/CBa+rCFmYAzmm3VQ=="
        }
    ],
    "id":1,
    "version":"1.0"
}
{
    "result":[],
    "id":1
}

Example for JSON get

JSON

{
    "method":"getSecretData",
    "params":[
        {
            "encKey":"hCkxUu4WydqDwrlq+PsSSxBaIVbPFNeCU7XYgBC9bVmXvcTORXMdY5FeSr3LYu9WywFbh1WwTBW/S+xTPHZQXhQMUsWEFQwUSldm5xK8vhOcdzGe8kdrixAL6zL9qx6rioR95gF50FO1RRVS7jdsabPvHK5gXZHM9B2h24QKON1FeTkYVGKcf8J3JJp9gEWeNYG2bfMSvnS9qrn2bLXgAX71vwEz7Btm/+qmX7/nsrL5QGBdbgxUlK7q5JzZxOdDuh592lfdEoMIgFR144XAnhfqyCcuZLJ/60VjOpREQ17vTj6+NNVrSOIq4eHnBlB7SfFWM/CBa+rCFmYAzmm3VQ=="
        }
    ],
    "id":1,
    "version":"1.0"
}
{
    "result":[
        {
           "secretData":"G9KgQDustrxplKFcy9fnVQ=="
        }
    ],
    "id":1
}

{
    "method":"getSecretData",
    "params":[
        {
            "encKey":"hCkxUu4WydqDwrlq+PsSSxBaIVbPFNeCU7XYgBC9bVmXvcTORXMdY5FeSr3LYu9WywFbh1WwTBW/S+xTPHZQXhQMUsWEFQwUSldm5xK8vhOcdzGe8kdrixAL6zL9qx6rioR95gF50FO1RRVS7jdsabPvHK5gXZHM9B2h24QKON1FeTkYVGKcf8J3JJp9gEWeNYG2bfMSvnS9qrn2bLXgAX71vwEz7Btm/+qmX7/nsrL5QGBdbgxUlK7q5JzZxOdDuh592lfdEoMIgFR144XAnhfqyCcuZLJ/60VjOpREQ17vTj6+NNVrSOIq4eHnBlB7SfFWM/CBa+rCFmYAzmm3VQ=="
        }
    ],
    "id":1,
    "version":"1.0"
}
{
    "result":[
        {
           "secretData":"G9KgQDustrxplKFcy9fnVQ=="
        }
    ],
    "id":1
}

4.Implementation Guide

The monitor generates an RSA public/private key pair when powered on. RSA key generation is time-consuming. Set the bit size and management method based on your monitor specifications.

Client Initialization Procedure

1. Call “getPublicKey” to retrieve the monitor’s public key.
2. Generate an AES symmetric key and encrypt it with the RSA public key to create encKey.
3. Use these keys to call the encryption API.

Note:
Do not change keys after initialization to maintain consistency.

The encryption key size can be defined by each system. Use a key size that considers security. Clients can use the same symmetric key for different API calls. Additionally, if necessary, clients can recreate the symmetric key and encKey to improve security.

Error Handling

If the encryption module fails to encrypt or decrypt due to an invalid state such as key mismatch, the monitor returns a 40002 Encryption Failed error. If the client receives this error, retry the initialization procedure (starting from calling getPublicKey).

In REST API, display resources are represented using the standard URI structure defined in RFC 3986. Please note that URIs are provided by the display and cannot be changed or modified on the client side.

Scheme Definition