From 8d4db0062fa97c1712b4a3c7babde3c0dd901219 Mon Sep 17 00:00:00 2001 From: Bertware Date: Sat, 12 Dec 2020 21:15:36 +0100 Subject: [PATCH] Fix markdown for json rpc api documentation, minor improvement to api documentation (#716) * Fix markdown typo * Fix a markdown type (duplicate ```), add an example with a string as jsonrpc id to make it clear that not only integers are supported * Improve JSON RPC id documentation --- doc/json_rpc_api/v2_0_0.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/doc/json_rpc_api/v2_0_0.md b/doc/json_rpc_api/v2_0_0.md index be245e19..8a3aaef2 100644 --- a/doc/json_rpc_api/v2_0_0.md +++ b/doc/json_rpc_api/v2_0_0.md @@ -101,6 +101,11 @@ WebSockets receive Notifications of events. Connect a client, and you will event The client that sends a "Set" command will receive a Response, while the other connected control clients will receive a Notification "On" event. Commands can be sent in a [Batch](http://www.jsonrpc.org/specification#batch). The server will reply with a Batch and send a Batch notification to the other clients. This way the volume of multiple Snapclients can be changed with a single Batch Request. +Each JSON RPC request and response contains an identifier in the `id` field, which can be used to link responses to the request that caused them, as defined in the JSON RPC specification: + + An identifier established by the Client that MUST contain a String, Number, or NULL value if included. + If it is not included it is assumed to be a notification. The value SHOULD normally not be Null [1] and Numbers SHOULD NOT contain fractional parts [2] + Clients should call `Server.GetStatus` to get the complete picture. The Server JSON object contains a list of Groups and Streams. Every Group holds a list of Clients and a reference to a Stream. Clients, Groups and Streams are referenced in the "Set" commands by their `id`. @@ -185,12 +190,12 @@ The Server JSON object contains a list of Groups and Streams. Every Group holds ### Client.SetVolume #### Request ```json -{"id":8,"jsonrpc":"2.0","method":"Client.SetVolume","params":{"id":"00:21:6a:7d:74:fc","volume":{"muted":false,"percent":74}}} +{"id":"8","jsonrpc":"2.0","method":"Client.SetVolume","params":{"id":"00:21:6a:7d:74:fc","volume":{"muted":false,"percent":74}}} ``` #### Response ```json -{"id":8,"jsonrpc":"2.0","result":{"volume":{"muted":false,"percent":74}}} +{"id":"8","jsonrpc":"2.0","result":{"volume":{"muted":false,"percent":74}}} ``` #### Notification @@ -385,7 +390,7 @@ The Server JSON object contains a list of Groups and Streams. Every Group holds ### Client.OnVolumeChanged ```json -{"jsonrpc":"2.0","method":"Client.OnVolumeChanged","params":{"id":"00:21:6a:7d:74:fc","volume":{"muted":false,"percent":74}}}``` +{"jsonrpc":"2.0","method":"Client.OnVolumeChanged","params":{"id":"00:21:6a:7d:74:fc","volume":{"muted":false,"percent":74}}} ``` ### Client.OnLatencyChanged @@ -410,7 +415,7 @@ The Server JSON object contains a list of Groups and Streams. Every Group holds ### Group.OnNameChanged ```json -{"jsonrpc":"2.0","method":"GrClient.OnNameChanged","params":{"id":"4dcc4e3b-c699-a04b-7f0c-8260d23c43e1","name":"GroundFloor"}} +{"jsonrpc":"2.0","method":"Group.OnNameChanged","params":{"id":"4dcc4e3b-c699-a04b-7f0c-8260d23c43e1","name":"GroundFloor"}} ``` ### Stream.OnUpdate