nymea/doc/jsonrpc.qdoc

/*!
    \page jsonrpc.html
    \title JSON-RPC API
    \ingroup jsonrpc

    \brief The JSON RPC interface represents a TCP socket connection using plaintext string communication.

    \section1 Description

    The JSON RPC interface represents a TCP socket connection using plaintext string communication.
    Messages are exchanged using the JSON format. Please note that this is not a REST API as the
    transport channel is not based on HTTP. It is an internal RPC mechanism to allow communication
    between the guh Server and the main controller interface. This communication socket is not meant
    to be exported to the outside of the of the systen as it allows arbitrary commands to manipulate
    the system.

    The JSON message protocol communicates by exchanging JSON Objects with the following properties:
    \list
        \li \code "id": integer \endcode
            The id should be a unique identifier for the message. Any server response will contain the
            same id allowing to match responses to requests/commands. This parameter is mandatory.
        \li \code "method": string \endcode
            The method field holds the method to be executed. Methods are grouped into namespaces. The
            method string consists of two parts, the namespace and the method name, separated by a dot.
            This parameter is mandatory.
            (Example: \c"JSONRPC.Introspect")
        \li \code "params": object \endcode
            The params contains any JSON object. This parameter is optional and differs according to
            the requested method.
    \endlist

    The JSONRPC API is self documenting and can be introspected by calling \c"JSONRPC.Introspect".

    Parameters are optional if the type is the type is prefixed with "o:" for optional.

    \section1 Communicating with the server
    The server listens by default on TCP port 2222 for incoming TCP connections. It will respond to incoming connections with a some information about the server. Telnet can be used to issue commands for testing.

    An example how to communicate with the API using telnet on the same host where the guh server
    is running:
    \code
        $  telnet localhost 2222
    \endcode
    \code    
        Trying 127.0.0.1...
	Connected to localhost.
	Escape character is '^]'.
	{
	    "id": 0,
	    "protocol version": 28,
	    "server": "guh JSONRPC interface",
	    "version": "0.6.0"
	}
    \endcode
    Now the connection is established and waits for commands.

    \section1 Classes

    \annotatedlist json


    \section1 Examples

    \section2 Introspect API
    \section3 Request
    \code
    {
        "id": 1,
        "method":"JSONRPC.Introspect"
    }
    \endcode
    \section3 Response
    \code
    {
        "id": 1,
        "params": {
            "methods": {
                ...
                "Devices.GetSupportedDevices": {
                    "description": "Returns a list of supported Device classes.",
                    "params": {
                    },
                    "returns": {
                        "deviceClasses": [
                            "$ref:DeviceClass"
                        ]
                    }
                },
                ...
            },
            "types": {
                ...
                "DeviceClass": {
                    "actions": [
                        "$ref:ActionType"
                    ],
                    "id": "uuid",
                    "name": "string",
                    "params": [
                        "$ref:ParamType"
                    ],
                    "states": [
                        "$ref:StateType"
                    ],
                    "events": [
                        "$ref:EventType"
                    ]
                },
                ...
            }
        },
        "status": "success"
    }
    \endcode

    \section2 Getting a list of supported devices
    \section3 Request
    \code
    {
        "id":1,
        "method":"Devices.GetSupportedDevices"
    }
    \endcode

    \section3 Response:
    \code {
        "id": 1,
        "params": {
            "deviceClasses": [
                {
                    "actions": [
                    ],
                    "id": "{bd216356-f1ec-4324-9785-6982d2174e17}",
                    "name": "WiFi Device",
                    "params": [
                        {
                            "name": "mac",
                            "type": "string"
                        }
                    ],
                    "states": [
                        {
                            "id": "{cb43e1b5-4f61-4538-bfa2-c33055c542cf}",
                            "name": "inRange",
                            "type": "bool"
                        }
                    ],
                    "events": [
                        {
                            "id": "{7cae711a-a0af-41b4-b3bf-38d3e23b41ba}",
                            "name": "inRange",
                            "params": [
                                {
                                    "name": "inRange",
                                    "type": "bool"
                                }
                            ]
                        }
                    ]
                }
                ...
            ]
        }
        "status": "success"
    }
    \endcode
    
    \section1 Newest JSON-RPC API
    
    \quotefile tests/auto/api.json
*/