JSON-RPC request and response example

The Audio Control API uses JSON-RPC with some extensions and restrictions. JSON-RPC is a light communication protocol.

The API uses three types of messages.

Set messages: to set some parameters on the device; the response is usually empty.
Get messages: to get some parameters from the device; the response contains the requested values.
Notification messages: messages sent from device without a request from the client, to notify the client about a parameter change.

Get and set messages include an id parameter. The id parameter is used to associate a response with the originating request. Notifications do not include an ID.

Below are some examples:

JSON-RPC request example

{
  "method": "echo",
  "params": ["Hello Audio Control API"],
  "id": 1, 
  "version": "1.0"
}

JSON-RPC response example

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

The Audio Control API adapts some extensions and restrictions to keep APIs simple and easy-to-use. For information for each API, see the API references.

Extensions

If the request succeeds, the error member is skipped in the response. On the other hand, if the request fails, the result member is skipped.
The error value is an array, defined as [error_code, error_message], where error_code is an integer and error_message is a string.
The client must set the version member in the request. The version member is of type string, and the version format is 2 numbers separated by dot (for example, "1.0"). For details about each API version.

Restrictions

For each API, the params and result values are fixed-length arrays.
For some APIs, the result member is optional in the response.
The id member is an integer. The value 0 (zero) MUST NOT be used. The client can set the id, and its valid range is "1" to "2147483647" (0x00000001 to 0x7FFFFFFF), inclusive.