nymea/doc/jsonrpc.qdoc

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

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

    \chapter Communicating with the server

    The JSON RPC interface represents a 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 nymea Server and the main controller interface. This communication socket is not meant
    to be exported to the outside of the of the system as it allows arbitrary commands to manipulate
    the system.

    \section1 Message format

    \section2 Request message

    The request message is a JSON objects and contains following properties:

    \code
        {
            "id": integer,
            "method": "Namespace.Method",
            "o:token": "string",
            "o:params" { }
        }
    \endcode

    \note \b M = mandatory, \b O = optional

    \table
        \row
            \li \tt id
            \li \b M
            \li integer
            \li 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.
        \row
            \li \tt method
            \li \b M
            \li string
            \li 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
                (i.e: \l{JSONRPC.Introspect}).

                \b{See also:} \l{Methods}

        \row
            \li \tt token
            \li \b O
            \li string
            \li The token property contains the authentication token received from the \l{Authentication}{authentication}
                process. This parameter is optional and only required if the authentication is enabled.

                \b{See also:} \l{Authentication}

        \row
            \li \tt params
            \li \b O
            \li object
            \li The params contains any JSON object. This parameter is optional and differs according to
                the requested method.

    \endtable


    \section2 Response message

    The response message is a JSON objects and contains following properties:

    \code
        {
            "id": integer,
            "status": "string",
            "o:params" { },
            "o:error": "string"
        }
    \endcode

    \note \b M = mandatory, \b O = optional

    \table
        \row
            \li \tt id
            \li \b M
            \li integer
            \li The id matching to the requested \tt {id}.
        \row
            \li \tt status
            \li \b M
            \li string
            \li The status property can be:
                \list
                    \li \tt {"success"}
                    \li \tt {"error"}
                    \li \tt {"unauthorized"}
                \endlist
        \row
            \li \tt params
            \li \b O
            \li object
            \li The params contains any JSON object. This parameter is optional and differs according to
                the requested method.
        \row
            \li \tt error
            \li \b O
            \li string
            \li The error property will only be added if a protocol related error happen and the \tt {"status"} property is \tt {error} or \tt {unauthorized}.
                The value contains a description of the API error.
    \endtable


    If there is an error on the JSON RPC transport layer, the server will respond with an error message. This error is related
    to the protocol layer of the communication.

    If the server needs a very long time to process a request or there happens any error, the JSON RPC server will timeout a request.
    The timeout interval is 30 seconds.

    \section1 Handshake

    Once connected to the socket, the first thing you have to do is to initiate the Handshake. This is done by calling the
    JSONRPC.Hello message. The server will reply with with information about the running instance. Use this handshake message
    to configure basic parameters for the connection, for instance the locale.
    
    Here is an example of a handshake request:

    \code
    {
        "id": 0,
        "method": "JSONRPC.Hello",
        "params": {
            "locale": "de_DE"
        }
    }
    \endcode
    
    And the according reply of the server.
    \code
    {
        "id": 0,
        "status": "success",
        "params": {
            "name": "My nymea",
            "protocol version": "2.0",
            "authenticationRequired": false,
            "initialSetupRequired": false,
            "pushButtonAuthAvailable": false,
            "server": "nymea",
            "locale": "de_DE",
            "uuid": "{42842b0f-a7bb-4a94-b624-a55f31c5603e}",
            "version": "0.12.1"
        }
    }
    \endcode

    \table
        \row
            \li \tt id
            \li integer
            \li It will be the same ID as the request
        \row
            \li \tt status
            \li string
            \li Whether or not the JSONRPC request was successfull.
        \row
            \li \tt params
            \li json object
            \li The response parameters
        \row
            \li \tt name
            \li string
            \li This field represents the name of the server you are connected to. This name is user defined an can be changed
                using \l{Configuration.SetServerName}.
        \row
            \li \tt {protocol version}
            \li string
            \li The field represents the API version of the server you are connected to (\tt{Major.Minor}). This should be used for API
                compatibility checks. A major version bump indicates a breaking API change, a minor version bump is means something was added and
                does not break the API compatibility.
        \row
            \li \tt authenticationRequired
            \li bool
            \li If this property is true, a client must perform the authentication process before being able to interact with the API.

                \b{See also:} \l{Authentication}
        \row
            \li \tt initialSetupRequired
            \li bool
            \li This property indicates if the server was set up already. A server is set up if a user has been created.
                If the \tt authenticationRequired property is \tt{false}, this field can be ignored.
        \row
            \li \tt pushButtonAuthAvailable
            \li bool
            \li This property indicates if the server has a running push-button agent and therefore the push-button authentication available.
                If the \tt authenticationRequired property is \tt{false}, this field can be ignored.

                \b{See also:} \l{Push-button authentication}
        \row
            \li \tt server
            \li string
            \li This property holds the name of the server. This name can not be changed.
        \row
            \li \tt locale
            \li string
            \li This property holds the locale for this connection. It should generally match with the locale you requested in the Hello message.
                If you did not pass any locale request, the server default will be used which can be configured using Settings.SetLanguage. However,
                Configuration.SetLanguage is deprecated as of 2.0. Clients should request a per-connection locale.
        \row
            \li \tt uuid
            \li string
            \li This property holds the UUID of the server and can be used as a unique identifier.
        \row
            \li \tt version
            \li string
            \li This property holds the build version of the server.

    \endtable

    Note that the client can re-initiate the handshake at any point. This might be useful to check whether server properties have changed (e.g.
    the initialSetup has been performed by another client in the meantime, or to change connection parameters for the connection, for example
    the locale.

    \section1 Sending a request

    Once the \l{Handshake}{handshake} has been performed, normal communication with the server can begin.
    In order to send a request to the server, the client has to send an API message according to the format descibed \l{Message format}{here}.

    The JSON content should always be sent as a compack JSON Object (without spaces, tabs and new line characters within the object \tt{{...}}).
    At the end of this compact JSON string the payload must be terminated with the \tt{\\n} character. This makes sure, that the parsing of the
    message is easier and a single message can be split in multiple cunckes during the transport. The client parsing should work the same way.

    Note that the Handshake already follows this model, that is, the Handshake is like any other regular method.

    In order to demonstrate this with an example, the \l{JSONRPC.Hello} request could look like this:

    \note Send following content as compact JSON ending with \tt{\\n}:

    \code
    {"id":122,"method":"JSONRPC.KeepAlive", "params": {"sessionId": "my-session"}}

    \endcode

    The \tt id can be a random integer, just make sure there are no other commands with the same id around. The easiest way to do that
    is incrementing the id with each new request. The \l{JSONRPC.KeepAlive} method requires one additional parameter,  a sessionId.

    The server will return a response for this request. The response will have the same \tt id as your request. The json content of the response will
    also be a compact JSON string ending with the \tt{\\n} character.

    \code
    {"id":122,"params":{"success": true, "sessionId": "my-session"}}

    \endcode

    \section1 Getting notifications

    In order to enable/disable notifications on your socket, the methods \l{JSONRPC.SetNotificationStatus} can be used. By default,
    the notifications on a new created connection are disabled. If you get disconnected, the notification have to
    be enabled again on the next connection.

    Once the notifications are enabled, the server will start notifying you with all different notifications described in section \l{Notifications}.

    A notification message has following properties:

    \code
        {
            "id": integer,
            "notification": "Namespace.Notification",
            "o: params": { }

        }
    \endcode

    \note \b M = mandatory, \b O = optional

    \table
        \row
            \li \tt id
            \li \b M
            \li integer
            \li The id should be a unique identifier for the message. The notification id will be increased for each notification sent to your connection.
        \row
            \li \tt notification
            \li \b M
            \li string
            \li The notification field holds the name of this notification. Notifications are grouped into namespaces like the methods.
                The notification string consists of two parts, the namespace and the notification name, separated by a dot.
                This property can be used to check if a received message is a response to a request or a notification.

                \b{See also:} \l{Methods}
        \row
            \li \tt params
            \li \b O
            \li object
            \li The params contains any JSON object. This parameter is optional and differs according to each \l{Notifications}{notification}.
    \endtable

    \chapter Authentication
    
    The API has an authentication mechanism, which makes sure that no unauthorized network participent can perform actions or get information from the server.
    For using the authentication the \tt authenticationRequired property in the \l{Handshake}{handshake} must be \tt{true}.
    
    There are some methods, which can be called even without authentication:
    \list
        \li \l{JSONRPC.Hello}
        \li \l{JSONRPC.Introspect}
        \li \l{JSONRPC.CreateUser} (only if there is no user yet)
        \li \l{JSONRPC.RequestPushButtonAuth}
        \li \l{JSONRPC.Authenticate}
    \endlist


    \note If you are using an authenticated connection, please make sure you are using an encrypted transport layer, otherwise you have
    a serious security problem.

    In order to verify each request sent to the server, the client has to send a token in each JSON RPC message (see \l{Request message}{Request message - token}).
    There are two different types of authentication in order to get a token:
    \list
        \li \l{Username and password}
        \li \l{Push-button authentication}
    \endlist

    If both authentication methods are available, the \l{Push-button authentication} should be preferred.

    \section1 Username and password

    If the \l{Handshake}{handshake} property \tt initialSetupRequired is \tt{true}, there is no user configured yet. This means the
    you have to create a user before you are abele to authenticate.

    \section2 Create a user
    
    Currently the nymead server is a single user only system and allows only one user. Creating a new user is only allowed if
    the \l{Handshake}{handshake} property \tt initialSetupRequired is \tt{true}.

    Call the \l{JSONRPC.CreateUser} method with the username (should be an email address) and password. The returned \l{UserError}
    informs you about the result. If the user was created successfully, you can use those credentials for authenticate your connection.
    
    \section2 Authenticate
    
    If you have already created the system user using \l{JSONRPC.CreateUser}, you can now call the method \l{JSONRPC.Authenticate}
    using the same user name, password and the client device name. This name should give information about the device using this token
    i.e. "Phone xy" or "Cool client application xy". This information helps you later to associate the token with this client device.

    If the user name and password are ok, the server will return the token which can be used for further communication. This token can
    be stored together with the server uuid ont he client side. The client does not need to reauthenticate until:

    \list
        \li The token gets rejected from the server
        \li The token gets deleted from on the client
        \li The token gets removed from the server
    \endlist

    \section1 Push-button authentication

    If the push button authentication is enabled, a client can only get a token if he has physical access to the device where the
    server is running. For this authentication method the \l{Handshake}{handshake} property \tt initialSetupRequired can be ignored.

    The Push-button authentication method works like this:

    \list
        \li The client initialtes the push authentication using \l{JSONRPC.RequestPushButtonAuth} containing the device name for token association.
        \li The server returns the status and a \tt{transactionId}. Now is the time to instruct the user how the button should be pressed.
        \li Once the user has pressed the button, the \l{JSONRPC.PushButtonAuthFinished} notification will be emitted. If there was no error
    and the authentication went fine, this notification contains the same transactionId for request matching and the token which can
    be used from now on.
    \endlist

    A possible case where the Push-button authentication could fail is a situation where 2 different clients request for a Push-button
    authentication. In that case the authentication will faile since it you cannot steal the button event from an other request.

    \section1 Removing a token

    If a device gets lost or you want to force a reauthentication to a client, a token can be removed from the system. This can be done
    using the \l{JSONRPC.RemoveToken} method. Once a token is removed, it can never be used again and the client owning that token
    can not perform any actions any more on this server until he re-authenticates again.
    
    \chapter API

    This section contains the complete API description of the current server. The JSON-RPC API is self documenting and
    can be introspected by calling \l{JSONRPC.Introspect}.

    Parameters are optional if the type is prefixed with \tt{"o:"} for optional.

    Specific API Types are prefixed with \tt{$ref:} and are documented in the \l{Types} section.

    \include jsonrpc-api.qdoc

*/