99 lines
4.6 KiB
Plaintext
99 lines
4.6 KiB
Plaintext
/*!
|
|
\page jsonrpc.html
|
|
\title JSON-RPC API
|
|
\ingroup jsonrpc
|
|
|
|
\brief The JSON RPC interface represents a socket connection using plaintext string communication.
|
|
|
|
\chapter Description
|
|
|
|
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 guh 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.
|
|
|
|
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
|
|
|
|
\chapter Handshake
|
|
|
|
Once connected to the socket, the server will send immediatly a handshake message. The handshake message
|
|
is a JSON object and contains all relevant information about the server and the API in order to start
|
|
communicationg with the server.
|
|
|
|
Here is an example of the handshare:
|
|
|
|
\code
|
|
{
|
|
"id": 0,
|
|
"name": "guh",
|
|
"protocol version": "1.2",
|
|
"authenticationRequired": false,
|
|
"initialSetupRequired": false,
|
|
"pushButtonAuthAvailable": false,
|
|
"server": "guhIO",
|
|
"language": "de_DE",
|
|
"uuid": "{42842b0f-a7bb-4a94-b624-a55f31c5603e}",
|
|
"version": "0.8.3"
|
|
}
|
|
\endcode
|
|
|
|
|
|
\list
|
|
\li \code "id": int \endcode
|
|
The id in the handshake has always the value 0. This is the first message during connection.
|
|
\li \code "name": string \endcode
|
|
This field represents the name of the server you are connected to. This name is user defined an can be changed.
|
|
(Example: \c"JSONRPC.Introspect")
|
|
\li \code "protocol version": string \endcode
|
|
The field represents the API version of the server you are connected to. This should be used for API compatibility checks
|
|
\li \code "authenticationRequired": bool \endcode
|
|
If this property is true, a client must perform the authentication process before beeing able to interact with the API. See section \l{Authentication} for more information.
|
|
\li \code "initialSetupRequired": bool \endcode
|
|
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.
|
|
\li \code "pushButtonAuthAvailable": bool \endcode
|
|
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.
|
|
\li \code "server": string \endcode
|
|
This property holds the name of the server. This name can not be changed.
|
|
\li \code "language": string \endcode
|
|
This property holds the language of the server. The language can be changed in the settings.
|
|
\li \code "uuid": string \endcode
|
|
This property holds the UUID of the server and can be used as a unique identifier.
|
|
\li \code "version": string \endcode
|
|
This property holds the build version of the server.
|
|
\endlist
|
|
|
|
|
|
\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}.
|
|
|
|
\section2 Create a user
|
|
|
|
|
|
|
|
\section2 Authenticate
|
|
|
|
|
|
\chapter API
|
|
\include jsonrpc-api.qdoc
|
|
|
|
\section1 Newest JSON-RPC API
|
|
|
|
\quotefile tests/auto/api.json
|
|
*/
|