3pp-mirror/snapcast
1
0
Fork 0
mirror of https://github.com/badaix/snapcast.git synced 2025-08-04 00:59:32 +02:00
Code Issues Projects Releases Packages Wiki Activity

Update v2_0_0.md

Browse source 
Add details regarding HTTP APIs (POST and WebSocket)
This commit is contained in:
Kevin Eady 2020-07-02 23:27:59 +02:00 • committed by Johannes Pohl
parent b155efc193
commit 11ee2319c9
1 changed files with 81 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

85
doc/json_rpc_api/v2_0_0.md
View file

@ -1,10 +1,15 @@
Snapcast JSON RPC Control API
=============================
Snapcast can be controlled with a [JSON-RPC 2.0](http://www.jsonrpc.org/specification) API over a raw TCP-Socket interface on port 1705.
Single JSON Messages are new line delimited ([ndjson](http://ndjson.org/)).
## Raw TCP sockets
For simple tests you can fire JSON commands on a telnet connection and watch Notifications coming in:
Snapcast can be controlled with a [JSON-RPC 2.0](http://www.jsonrpc.org/specification)
API over a raw TCP-Socket interface on port 1705.
Single JSON Messages are new line delimited ([ndjson](http://ndjson.org/)).
For simple tests you can fire JSON commands on a telnet connection and watch
Notifications coming in:
```json
$ telnet localhost 1705
@ -19,7 +24,79 @@ Escape character is '^]'.
{"jsonrpc":"2.0","method":"Client.OnConnect","params":{"client":{"config":{"instance":1,"latency":0,"name":"","volume":{"muted":false,"percent":74}},"connected":true,"host":{"arch":"x86_64","ip":"127.0.0.1","mac":"00:21:6a:7d:74:fc","name":"T400","os":"Linux Mint 17.3 Rosa"},"id":"00:21:6a:7d:74:fc","lastSeen":{"sec":1488065507,"usec":820050},"snapclient":{"name":"Snapclient","protocolVersion":2,"version":"0.11.0-beta-1"}},"id":"00:21:6a:7d:74:fc"}}
```
In the following the supported Requests and Notifications are described.
## HTTP
Snapcast can also be controlled on port 1780 using the HTTP protocol to (1) send
a single `POST` request or (2) create a long-lived `WebSocket`.
For simple tests, you can fire JSON commands directly within your browser.
One-shot `POST` requests receive only the immediate response of the request,
whereas long-lived `WebSocket`s will also receive Notifications similar to the
telnet connection above:
```js
const host = '127.0.0.1:1780';
const request = {
'id': 0,
'jsonrpc': '2.0',
'method': 'Server.GetRPCVersion'
};
// XHR
const xhr = new XMLHttpRequest();
xhr.open('POST', `http://${host}/jsonrpc`);
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.setRequestHeader('Accept', 'application/json');
xhr.addEventListener('load', ({ currentTarget: xhr }) => {
console.log(JSON.parse(xhr.responseText)); // {"id":1,"jsonrpc":"2.0","result":{"major":2,"minor":0,"patch":0}}
});
xhr.send(JSON.stringify(++request.id && request));
// Fetch
fetch(`http://${host}/jsonrpc`, {
method: 'POST',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: JSON.stringify(++request.id && request)
})
.then(response => response.json())
.then(content => console.log(content)); // {"id":2,"jsonrpc":"2.0","result":{"major":2,"minor":0,"patch":0}}
// Fetch with await/async
const response = await fetch(`http://${host}/jsonrpc`, {
method: 'POST',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: JSON.stringify(++request.id && request)
});
const content = await response.json();
console.log(content); // {"id":3,"jsonrpc":"2.0","result":{"major":2,"minor":0,"patch":0}}
// WebSocket
const ws = new WebSocket(`ws://${host}/jsonrpc`);
ws.addEventListener('message', (message) => {
console.log(JSON.parse(message.data)); // {"id":4,"jsonrpc":"2.0","result":{"major":2,"minor":0,"patch":0}}
});
ws.addEventListener('open', () => ws.send(JSON.stringify(++request.id && request)));
/*
WebSockets receive Notifications of events. Connect a client, and you will eventually see in your console:
{
"jsonrpc": "2.0",
"method": "Client.OnConnect",
"params": { ... }
}
*/
```
## Requests and Notifications
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.