this class provides the REST client API More...

Inheritance diagram for RestClient::RestClient:

Public Member Functions
	addDefaultHeaders (hash h)
	adds default headers to each request; these headers will be sent in all requests but can be overridden in requests as well More...

	constructor (hash opts, softbool do_not_connect)
	calls the base class HTTPClient constructor and optionally connects to the REST server More...

	decodeResponse (reference h, *reference info)
	decodes the response

hash	del (string path, any body, reference info, hash hdr)
	sends an HTTP DELETE request to the REST server and returns the response More...

hash	doRequest (string m, string path, any body, reference info, softbool decode_errors, *hash hdr)
	sends an HTTP request to the REST server and returns the response More...

hash	get (string path, any body, reference info, hash hdr)
	sends an HTTP GET request to the REST server and returns the response More...

hash	getDefaultHeaders ()
	returns the hash of default headers to sent in all requests More...

*string	getSendEncoding ()
	returns the current data content encoding (compression) object or NOTHING if no encoding option is set; see EncodingSupport for valid options More...

string	getSerialization ()
	returns the current data serialization format currently in effect for the object (see DataSerializationOptions for possible values) More...

hash	post (string path, any body, reference info, hash hdr)
	sends an HTTP POST request to the REST server and returns the response More...

private nothing	prepareMsg (reference body, reference hdr, string ct="Content-Type")
	sets up the Content-Type header and encodes any body for sending

private nothing	preparePath (reference path)
	sets up the path for the HTTP request URI

hash	put (string path, any body, reference info, hash hdr)
	sends an HTTP PUT request to the REST server and returns the response More...

	setContentEncoding (string enc="auto")
	sets the request and desired response encoding for the object; see EncodingSupport for valid options More...

	setSendEncoding (string enc="auto")
	change the data content encoding (compression) option for the object; see EncodingSupport for valid options More...

	setSerialization (string data="auto")
	change the serialization option for the object; see DataSerializationOptions for valid options More...

Public Attributes
const	Accept = AcceptList.join(",")
	Accept header value.

const	AcceptList
	Accept header list.

const	CompressionThreshold = 1024
	default threadhold for data compressions; transfers smaller than this size will not be compressed

const	DataDeserializationSupport
	Data deserialization support MIME types to codes and de/serialization functions.

const	DataSerializationOptions
	Data serialization options; this is a hash to simulate a set of strings. More...

const	DataSerializationSupport
	Data serialization support mapping codes to MIME types and de/serialization functions.

const	DefaultHeaders
	default HTTP headers (Content-Type is added before sending)

const	EncodingSupport
	Send content encoding options. More...

const	Version = "1.3"
	RestClient Version.

const	VersionString = sprintf("Qore-RestClient/%s", RestClient::Version)
	RestClient Version String.

Detailed Description

this class provides the REST client API

Member Function Documentation

RestClient::RestClient::addDefaultHeaders ( hash h )

adds default headers to each request; these headers will be sent in all requests but can be overridden in requests as well

Example:: # disable gzip and bzip encoding in responses

$rest.addDefaultHeaders(("Accept-Encoding": "compress"));

Parameters

h	a hash of headers to add to the default headers to send on each request

Note: default headers can also be set in the constructor

See also: RestClient::getDefaultHeaders()

Since: RestClient 1.3

RestClient::RestClient::constructor	(	*hash	opts,
		*softbool	do_not_connect
	)

calls the base class HTTPClient constructor and optionally connects to the REST server

Example:: my RestClient $rest(("url": "http://localhost:8001/rest"));

Parameters

opts

valid options are:

connect_timeout: The timeout value in milliseconds for establishing a new socket connection (also can be a relative date-time value for clarity, ex: 20s)
data: a data serialization option; if not present defaults to "auto"
default_path: The default path to use for new connections if a path is not otherwise specified in the connection URL
default_port: The default port number to connect to if none is given in the URL
headers: an optional hash of headers to send with every request, these can also be overridden in request method calls
http_version: Either '1.0' or '1.1' for the claimed HTTP protocol version compliancy in outgoing message headers
max_redirects: The maximum number of redirects before throwing an exception (the default is 5)
proxy: The proxy URL for connecting through a proxy
send_encoding: a send data encoding option or the value "auto" which means to use automatic encoding; if not present defaults to no content-encoding on sent message bodies
content_encoding: for possible values, see EncodingSupport; this sets the send encoding (if the "send_encoding" option is not set) and the requested response encoding
timeout: The timeout value in milliseconds (also can be a relative date-time value for clarity, ex: 30s)
url: A string giving the URL to connect to

do_not_connect if False (the default), then a connection will be immediately established to the remote server

Exceptions

RESTCLIENT-ERROR invalid option passed to constructor, unsupported data serialization, etc

Since: RestClient 1.2 the send_encoding option was added

hash RestClient::RestClient::del	(	string	path,
		any	body,
		*reference	info,
		*hash	hdr
	)

sends an HTTP DELETE request to the REST server and returns the response

Example:: my hash $ans = $rest.post("/orders/1");

Parameters

path	the URI path to add (will be appended to any root path given in the constructor)
body	an optional message body to be included in the request; if a value for this parameter is passed to the method, then the body will be serialized according to the serialization rules set in RestClient::constructor()
info	an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request
hdr	any headers to be sent with the request; headers here will override default headers for the object as well

Returns: A hash of headers received from the HTTP server with all key names converted to lower-case; if any message body is included in the response, it will be assigned to the value of the "body" key

Exceptions

DESERIALIZATION-ERROR the response body could not be deserialized (unknown Content-Type or invalid serialization)

See also

hash RestClient::RestClient::doRequest	(	string	m,
		string	path,
		any	body,
		*reference	info,
		*softbool	decode_errors,
		*hash	hdr
	)

sends an HTTP request to the REST server and returns the response

Example:: my hash $ans = $rest.doRequest("DELETE", "/orders/1");

Parameters

m	the HTTP method to be used; case is ignored (if not a valid method an `HTTP-CLIENT-METHOD-ERROR` exception is raised)
path	the URI path to add (will be appended to any root path given in the constructor)
body	an optional message body to be included in the request; if a value for this parameter is passed to the method, then the body will be serialized according to the serialization rules set in RestClient::constructor()
info	an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request
decode_errors	decode the message body with HTTP error responses and throw an exception based on the message body
hdr	any headers to be sent with the request; headers here will override default headers for the object as well

Returns: A hash of headers received from the HTTP server with all key names converted to lower-case; if any message body is included in the response, it will be assigned to the value of the "body" key

Exceptions

DESERIALIZATION-ERROR	the response body could not be deserialized (unknown `Content-Type` or invalid serialization)
HTTP-CLIENT-METHOD-ERROR	invalid HTTP method argument passed

See also

hash RestClient::RestClient::get	(	string	path,
		any	body,
		*reference	info,
		*hash	hdr
	)

sends an HTTP GET request to the REST server and returns the response

Example:: my hash $ans = $rest.get("/orders/1?info=verbose");

Parameters

path	the URI path to add (will be appended to any root path given in the constructor)
body	an optional message body to be included in the request; if a value for this parameter is passed to the method, then the body will be serialized according to the serialization rules set in RestClient::constructor()
info	an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request
hdr	any headers to be sent with the request; headers here will override default headers for the object as well

Returns: A hash of headers received from the HTTP server with all key names converted to lower-case; if any message body is included in the response, it will be assigned to the value of the "body" key

Exceptions

DESERIALIZATION-ERROR the response body could not be deserialized (unknown Content-Type or invalid serialization)

See also

hash RestClient::RestClient::getDefaultHeaders ( )

returns the hash of default headers to sent in all requests

Example:: my hash $h = $rest.getDefaultHeaders();

Returns: the hash of default headers to sent in all requests

Note: default headers can be set in the constructor and in addDefaultHeaders()

See also: RestClient::addDefaultHeaders()

Since: RestClient 1.3

*string RestClient::RestClient::getSendEncoding ( )

returns the current data content encoding (compression) object or NOTHING if no encoding option is set; see EncodingSupport for valid options

Example:: my *string $ce = $.rest.getSendEncoding();

Returns: the current data content encoding (compression) object or NOTHING if no encoding option is set; see EncodingSupport for valid options

See also

Since: RestClient 1.3

string RestClient::RestClient::getSerialization ( )

returns the current data serialization format currently in effect for the object (see DataSerializationOptions for possible values)

Example:: my string $ser = $rest.getSerialization();

Returns: the current data serialization format currently in effect for the object (see DataSerializationOptions for possible values)

See also: RestClient::setSerialization()

hash RestClient::RestClient::post	(	string	path,
		any	body,
		*reference	info,
		*hash	hdr
	)

sends an HTTP POST request to the REST server and returns the response

Example:: my hash $ans = $rest.post("/orders", ("product": "xyz123", "options": 500));

Parameters

path	the URI path to add (will be appended to any root path given in the constructor)
body	an optional message body to be included in the request; if a value for this parameter is passed to the method, then the body will be serialized according to the serialization rules set in RestClient::constructor()
info	an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request
hdr	any headers to be sent with the request; headers here will override default headers for the object as well

Returns: A hash of headers received from the HTTP server with all key names converted to lower-case; if any message body is included in the response, it will be assigned to the value of the "body" key

Exceptions

DESERIALIZATION-ERROR the response body could not be deserialized (unknown Content-Type or invalid serialization)

See also

hash RestClient::RestClient::put	(	string	path,
		any	body,
		*reference	info,
		*hash	hdr
	)

sends an HTTP PUT request to the REST server and returns the response

Example:: my hash $ans = $rest.put("/orders/1", ("action": "cancel"));

Parameters

path	the URI path to add (will be appended to any root path given in the constructor)
body	an optional message body to be included in the request; if a value for this parameter is passed to the method, then the body will be serialized according to the serialization rules set in RestClient::constructor()
info	an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request
hdr	any headers to be sent with the request; headers here will override default headers for the object as well

Returns: A hash of headers received from the HTTP server with all key names converted to lower-case; if any message body is included in the response, it will be assigned to the value of the "body" key

Exceptions

DESERIALIZATION-ERROR the response body could not be deserialized (unknown Content-Type or invalid serialization)

See also

RestClient::RestClient::setContentEncoding ( string enc = "auto" )

sets the request and desired response encoding for the object; see EncodingSupport for valid options

Example:: $rest.setContentEncoding("gzip");

Parameters

enc	the data content encoding (compression) option for requests and the desired response content encoding for the object; see EncodingSupport for valid options; if the value `"auto"` is passed then `"gzip"` encoding is used for outgoing requests and requested for responses

Exceptions

RESTCLIENT-ERROR invalid or unsupported data content encoding / compression option

See also

Since: restClient 1.3

RestClient::RestClient::setSendEncoding ( string enc = "auto" )

change the data content encoding (compression) option for the object; see EncodingSupport for valid options

Example:: $rest.setSendEncoding("gzip");

The default is to send requests unencoded/uncompressed.

Parameters

enc	the data content encoding (compression) option for the object; see EncodingSupport for valid options; if the value `"auto"` is passed then `"gzip"` encoding is used

Exceptions

RESTCLIENT-ERROR invalid or unsupported data content encoding / compression option

See also

RestClient::RestClient::setSerialization ( string data = "auto" )

change the serialization option for the object; see DataSerializationOptions for valid options

Example:: $rest.setSerialization("yaml");

Parameters

data	the serialization option for the object; see DataSerializationOptions for valid options

Exceptions

RESTCLIENT-ERROR invalid or unsupported serialization option

See also: RestClient::getSerialization()

Member Data Documentation

const RestClient::RestClient::DataSerializationOptions

Initial value:

= (
                "auto": True,
                "xml": True,
                "json": True,
                "yaml": True,
                )

Data serialization options; this is a hash to simulate a set of strings.

Data serialization options are as follows:

"auto": prefers in this order: json, yaml, xml-rpc
"xml": use only XML-RPC serialization
"json": use only JSON serialization
"yaml": use only YAML serialization

const RestClient::RestClient::EncodingSupport

Initial value:

= (
                "gzip": (
                    "ce": "gzip",
                    "func": \gzip(),
                    ),
                "bzip2": (
                    "ce": "bzip2",
                    "func": \bzip2(),
                    ),
                "deflate": (
                    "ce": "deflate",
                    "func": \compress(),
                    ),
                "identity": (
                    "ce": NOTHING,
                    ),
                )

Send content encoding options.

Send content encoding options are as follows:

"bzip": use bzip2 compression
"gzip": use gzip compression
"deflate": use deflate compression
"identity": use no content encoding

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

Member Data Documentation