Qore RestClient Module Reference  1.1
 All Classes Namespaces Functions Variables Groups Pages
RestClient::RestClient Class Reference

this class provides the REST client API More...

Inheritance diagram for RestClient::RestClient:

Public Member Functions

 constructor (*hash opts, *softbool do_not_connect)
 calls the base class HTTPClient constructor and optionally connects to the REST server More...
 
hash del (string path, any body, *reference info)
 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)
 sends an HTTP GET request to the REST server and returns the response 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)
 sends an HTTP POST request to the REST server and returns the response More...
 
hash put (string path, any body, *reference info)
 sends an HTTP PUT request to the REST server and returns the response 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 DataDeserializationSupport
 Data deserialization support MIME types to codes and de/serialization functions.
 
const DataSerializationOptions
 Data serialization options; this is a hash to similulate 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 Version = "1.0"
 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::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
optsvalid options are:
  • url: A string giving the URL to connect to
  • data: a data serialization option; if not present defaults to "auto"
  • default_port: The default port number to connect to if none is given in the URL
  • http_version: Either '1.0' or '1.1' for the claimed HTTP protocol version compliancy in outgoing message headers
  • default_path: The default path to use for new connections if a path is not otherwise specified in the connection URL
  • max_redirects: The maximum number of redirects before throwing an exception (the default is 5)
  • proxy: The proxy URL for connecting through a proxy
  • timeout: The timeout value in milliseconds (also can be a relative date-time value for clarity, ex: 30s)
  • 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)
do_not_connectif False (the default), then a connection will be immediately established to the remote server
Exceptions
RESTCLIENT-ERRORinvalid option passed to constructor, unsupported data serialization, etc
hash RestClient::RestClient::del ( string  path,
any  body,
*reference  info 
)

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

Example:
my hash $ans = $rest.post("/orders/1");
Parameters
paththe URI path to add (will be appended to any root path given in the constructor)
bodyan 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()
infoan 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
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-ERRORthe 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
mthe HTTP method to be used; case is ignored (if not a valid method an HTTP-CLIENT-METHOD-ERROR exception is raised)
paththe URI path to add (will be appended to any root path given in the constructor)
bodyan 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()
infoan 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_errorsdecode the message body with HTTP error responses and throw an exception based on the message body
hdrany headers to be sent with the request
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-ERRORthe response body could not be deserialized (unknown Content-Type or invalid serialization)
HTTP-CLIENT-METHOD-ERRORinvalid HTTP method argument passed
See Also
hash RestClient::RestClient::get ( string  path,
any  body,
*reference  info 
)

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

Example:
my hash $ans = $rest.get("/orders/1?info=verbose");
Parameters
paththe URI path to add (will be appended to any root path given in the constructor)
bodyan 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()
infoan 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
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-ERRORthe response body could not be deserialized (unknown Content-Type or invalid serialization)
See Also
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 
)

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
paththe URI path to add (will be appended to any root path given in the constructor)
bodyan 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()
infoan 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
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-ERRORthe response body could not be deserialized (unknown Content-Type or invalid serialization)
See Also
hash RestClient::RestClient::put ( string  path,
any  body,
*reference  info 
)

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

Example:
my hash $ans = $rest.put("/orders/1", ("action": "cancel"));
Parameters
paththe URI path to add (will be appended to any root path given in the constructor)
bodyan 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()
infoan 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
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-ERRORthe response body could not be deserialized (unknown Content-Type or invalid serialization)
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
datathe serialization option for the object; see DataSerializationOptions for valid options
Exceptions
RESTCLIENT-ERRORinvalid 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 similulate 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