Devious Fish
pianod JSON Request Overview

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 and password (both strings).

inRoom

accepts a dictionary containing room (string).

withSource

Accepts a dictionary named source containing either id (numeric) or both type and name (both strings).

Like the AS USER command-line counterpart, requests including asUser will close the connection when they complete (or fail).