YamlRpcClient Module Introduction

This module implements client-side support for a proprietary RPC-based protocol using YAML for serialization/deserialization of message data.

The following classes are provided by this module:

YAML-RPC Protocol Implementation

YAML-RPC is an HTTP-based RPC protocol; it is not a standard protocol, however it is based on JSON-RPC 1.1 and similar in approach to XML-RPC.

YAML-RPC has some technical advantages over JSON-RPC and XML-RPC when developing in Qore:

it is relatively fast
it supports the best data serialization for Qore data of all RPC protocols supported by Qore at the moment
it is concise while still being very easy to read.

The major drawback is that it is a proprietary protocol, which is why Qore will continue to support XML-RPC and JSON-RPC alongside YAML-RPC.

The information below provides technical information about how this proprietary YAML-RPC protocol is implemented; details which are not normally visible when using the YamlRpcClient class.

Request messages are sent as a YAML-encoded request string as the message body of an HTTP POST message. The "Content-Type" header should be set to MimeTypeYamlRpc (from Mime.qm), otherwise there are no special restrictions on the message headers.

Request and response message bodies must always be encoded with UTF-8 encoding.

YAML-RPC request strings are constructed as a simple YAML map with the following keys:

method: the string method name to call
params: any value giving the arguments for the method; if the method takes more than one argument, then the "params" key will hold a list of the arguments. The YamlRpcClient class will always package a single argument in a list.

Note that this YAML-RPC implementation uses the Qore YAML module to encode and decode YAML strings; this ensures maximum data fidelity when serializaing data; note that the Qore yaml module uses the proprietary !duration tag for durations, otherwise all other tags are standard YAML tags. For details on how Qore data is serialized and deserialized by the yaml module, please see the yaml module documentation.

The following is an example of a simple request message with headers:

POST YAML HTTP/1.1
Content-Type: application/x-yaml;charset=utf-8
Accept: application/x-yaml
User-Agent: Qore-YAML-RPC-Client/1.0
Accept-Encoding: deflate,gzip,bzip2
Connection: Keep-Alive
Host: localhost:8001
Content-Length: 49
{method: "omq.system.help", params: ["add-user"]}

YAML-RPC Non-Error Responses

Normal (non-error) responses are returned as a YAML map as well with the following key:

result: a map where the only key is the method name and the value is the value returned by the method.

For example, for the message above, the response message would be:

HTTP/1.1 200 OK
Content-type: application/x-yaml;charset=utf-8
Server: Qore-HTTP-Server/0.3.11.1
Connection: Keep-Alive
Date: Mon, 27 Sep 2010 10:34:06 GMT
Content-Encoding: deflate
Content-Length: 152
{result: {omq.system.add-user: {params: "username, password, descriptive_name, role_list, groups", category: "role based access control", maskargs: 1, description: "creates a new RBAC user"}}}

YAML-RPC Error Responses

Error responses are also returned as a YAML map with a single key, error, which is itself a map with the following keys:

name: always "YAMLRPCError"
code: an integer error code
message: an error message
error: an optional error value of any format

The following is an example error response message:

HTTP/1.1 200 OK
Content-type: application/x-yaml;charset=utf-8
Server: Qore-HTTP-Server/0.3.11.1
Connection: Keep-Alive
Date: Mon, 27 Sep 2010 10:38:06 GMT
Content-Encoding: deflate
Content-Length: 118
{error: {name: "YAMLRPCError", code: 105, message: "YAML-RPC-SERVER-UNKNOWN-METHOD: unknown method \"omq.system.none\""}}

Table of Contents

YamlRpcClient Module Introduction

YAML-RPC Protocol Implementation

YAML-RPC Non-Error Responses

YAML-RPC Error Responses

YamlRpcClient Module Release History

YamlRpcClient v1.1

YamlRpcClient v1.0