pianod2 JSON Requests
In addition to the traditional command-line, pianod
allows commands to be submitted as JSON. To differentiate,
“commands” refer to command-line style, while
“request” will refer to JSON style.
At present, JSON support is one-way. In the future, bidirectional JSON will be supported.
JSON request names and keys are case sensitive.
Message quoting should be done in accordance with the JSON specification.
When sent to pianod
, the request must be sent on a
single line; returns are treated as end-of-message. Requests split
over multiple lines will fail. Only one request can be sent per
line.
Any instruction can be sent as either a command line or
as a JSON request. The schema
command can be used to
generate a list of all requests, or details for a particular
request. See the commands section.
For example:
SCHEMA getSchema
203 Data
132 Information: All requests take the form:
132 Information: {"requestname": {request parameters/options...}}
132 Information: getSchema: Dictionary containing:
132 Information: 'request' (optional)
132 Information: List (0 or more members) of String (no control characters allowed)
204 No data or end of data
If we wanted to use JSON to request the schema for authenticating:
{ "getSchema": {"request": ["authenticate"] } }
203 Data
132 Information: authenticate: Dictionary containing:
132 Information: 'username' (mandatory)
132 Information: Requires also: password
132 Information: String (no control characters allowed)
132 Information: 'password' (mandatory)
132 Information: Requires also: username
132 Information: String (no control characters allowed)
204 No data or end of data
There are 3 special keys that can be used in the main dictionary of the request:
asUser
- Accepts a dictionary containing
username
andpassword
(both strings). inRoom
- accepts a dictionary containing
room
(string). withSource
- Accepts a dictionary named
source
containing eitherid
(numeric) or bothtype
andname
(both strings).
Like the AS USER
command-line counterpart, requests
including asUser
will close the connection when they
complete (or fail).