Introduction

Estimated reading time: 7 minutes

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.

Type Explanation
boolean A true or false value is stored.
boolean-array Multiple true or false values are stored in an array.
integer An integer number ranging from -2147483648 to 2147483647 is stored.
integer-array Multiple integer numbers are stored in an array.
double A double number ranging from -2.2250738585072014e-308 to 1.7976931348623157e+308 is stored.
double-array Multiple double numbers are stored in an array.
string A string value. Unless otherwise mentioned in each API spec, the string is encoded with UTF-8.
string-array Multiple string data are stored in an array.

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.

Multiplicity 1 : Required Once
? : Zero or Once
* : Zero or More
Default Default is the value that the data receiver must regard as if it were sent from the sender in case specific parameters are missing.
Date This product uses ISO 8601.
Country This product uses ISO 3166 alpha 2 and additional codes.

Authentication

Currently following authentication levels are defined.

Authentication Level Criteria
private Authentication required. The APIs that provide information which is not personal information (information that can be used to identify an individual), but information like device id or information that might differ with user of the device.
generic Authentication required. The APIs that control device or change device status.
none Authentication not required. The APIs that do not match above criteria.

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.

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

Service Description
guide The guide service provides an API to retrieve the list of supported services on the server.
appControl This service handles APIs that are for launching the application itself, and the accompanying manipulations related to specific applications .
audio This service handles APIs that are related to audio functions like volume, sound effects, and so on.
avContent This service handles the overall control of input and output of the device for AV contents and manipulating AV Contents itself on the device.
encryption This service handles APIs that are related to encryption.
system This service handles APIs that are related to basic device functions like as follows.
videoScreen This service handles APIs that are related to video screen functions.
Last modified: 6 Mar 2019