Qore RestClient Module Reference  1.4
RestClient::RestClient Class Reference

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...
 
hash del (string path, auto body, *reference< hash > info, *hash hdr)
 sends an HTTP DELETE request to the REST server and returns the response More...
 
hash doRequest (string m, string path, auto body, *reference< hash > info, softbool decode_errors=True, *hash hdr)
 sends an HTTP request to the REST server and returns the response More...
 
hash get (string path, auto body, *reference< hash > 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...
 
RestSchemaValidator::AbstractRestSchemaValidator getValidator ()
 returns the current validator object More...
 
hash patch (string path, auto body, *reference< hash > info, *hash hdr)
 sends an HTTP PATCH request to the REST server and returns the response More...
 
hash post (string path, auto body, *reference< hash > info, *hash hdr)
 sends an HTTP POST request to the REST server and returns the response More...
 
hash put (string path, auto body, *reference< hash > info, *hash hdr)
 sends an HTTP PUT request to the REST server and returns the response More...
 
hash sendAndDecodeResponse (*data body, string m, string path, hash hdr, *reference< hash > info, *softbool decode_errors)
 sends the outgoing HTTP message and recodes the response to data
 
 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 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.4"
 RestClient Version.
 
const VersionString = sprintf("Qore-RestClient/%s", RestClient::Version)
 RestClient Version String.
 

Static Public Attributes

static private
 tries to decode an error response
 

Private Member Functions

nothing prepareMsg (string method, string path, reference body, reference< hash > hdr, string ct="Content-Type")
 sets up the Content-Type header and encodes any body for sending
 
nothing preparePath (reference< string > path)
 sets up the path for the HTTP request URI
 

Static Private Member Functions

static decodeError (hash h, *reference< hash > info)
 decode any REST errors returned if possible
 

Detailed Description

this class provides the REST client API

Member Function Documentation

◆ addDefaultHeaders()

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
ha 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

◆ constructor()

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

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

Example:
RestClient rest(("url": "http://localhost:8001/rest"));
Parameters
optsvalid options are:
  • additional_methods: Optional hash with more but not-HTTP-standardized methods to handle. It allows to create various HTTP extensions like e.g. WebDAV. The hash takes the method name as a key, and the value is a boolean True or False: indicating if the method can accept a message body as well. Example:
    # add new HTTP methods for WebDAV. Both of them require body posting to the server
    ("additional_methods": ("PROPFIND": True, "MKCOL": True ));
  • 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)
  • 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 (note that the RestClient class will only compress outgoing message bodies over CompressionThreshold bytes in size)
  • 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 (note that the RestClient class will only compress outgoing message bodies over CompressionThreshold bytes in size)
  • swagger: the path to a Swagger 2.0 REST schema file for API validation; only used if validator not provided (see the Swagger module)
  • 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; if not given then the target URL will be taken from any validator option, if given by calling AbstractRestSchemaValidator::getTargetUrl()
  • validator: an AbstractRestSchemaValidator object to validate request and response messages; overrides swagger
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
Since
  • RestClient 1.2 the send_encoding option was added
  • RestClient 1.4 the validator and swagger options were added

◆ del()

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

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

Example:
hash ans = rest.del("/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; if present the hash will contain the following keys:
  • headers: a hash of outgoing HTTP request headers
  • request-uri: the request URI string sent (ex: "DELETE /services/async/38.0/job HTTP/1.1")
  • body-content-type: the outgoing message body Mime Content-Type value
  • response-headers: a hash of incoming HTTP headers in the response
  • chunked: set to True if the response was received with chunked transfer encoding
  • response-code: the HTTP response code
  • response-body: the raw message body in the response (after any content decoding)
  • response-serialization: the type of message serialization in the response; see DataSerializationOptions for possible values when used with the null REST schema validator
  • request-body: the raw message body in the request (before any content encoding)
  • request-serialization: the type of message serialization in the request; see DataSerializationOptions for possible values when used with the null REST schema validator
hdrany 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 deserialized to Qore data and 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-RECEIVE-ERRORif this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
  • "response-code": the HTTP response code given
  • "response-headers": a hash of response headers
  • "response-body": the decoded response body

Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.

See also

◆ doRequest()

hash RestClient::RestClient::doRequest ( string  m,
string  path,
auto  body,
*reference< hash info,
softbool  decode_errors = True,
*hash  hdr 
)

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

Example:
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; if present the hash will contain the following keys:
  • headers: a hash of outgoing HTTP request headers
  • request-uri: the request URI string sent (ex: "POST /services/async/38.0/job HTTP/1.1")
  • body-content-type: the outgoing message body Mime Content-Type value
  • response-headers: a hash of incoming HTTP headers in the response
  • chunked: set to True if the response was received with chunked transfer encoding
  • response-code: the HTTP response code
  • response-body: the raw message body in the response (after any content decoding)
  • response-serialization: the type of message serialization in the response; see DataSerializationOptions for possible values when used with the null REST schema validator
  • request-body: the raw message body in the request (before any content encoding)
  • request-serialization: the type of message serialization in the request; see DataSerializationOptions for possible values when used with the null REST schema validator
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; 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 deserialized to Qore data and 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
HTTP-CLIENT-RECEIVE-ERRORif this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
  • "response-code": the HTTP response code given
  • "response-headers": a hash of response headers
  • "response-body": the decoded response body

Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.

See also

◆ get()

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

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

Example:
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(); note that sending a message body with an HTTP GET request is not standards compliant; see HTTP GET Requests With a Message Body for more information; for maximum compatibility, use NOTHING for this argument when calling this method
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; if present the hash will contain the following keys:
  • headers: a hash of outgoing HTTP request headers
  • request-uri: the request URI string sent (ex: "GET /services/async/38.0/job HTTP/1.1")
  • body-content-type: the outgoing message body Mime Content-Type value
  • response-headers: a hash of incoming HTTP headers in the response
  • chunked: set to True if the response was received with chunked transfer encoding
  • response-code: the HTTP response code
  • response-body: the raw message body in the response (after any content decoding)
  • response-serialization: the type of message serialization in the response; see DataSerializationOptions for possible values when used with the null REST schema validator
  • request-body: the raw message body in the request (before any content encoding)
  • request-serialization: the type of message serialization in the request; see DataSerializationOptions for possible values when used with the null REST schema validator
hdrany 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 deserialized to Qore data and 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-RECEIVE-ERRORif this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
  • "response-code": the HTTP response code given
  • "response-headers": a hash of response headers
  • "response-body": the decoded response body

Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.

See also

◆ getDefaultHeaders()

hash RestClient::RestClient::getDefaultHeaders ( )

returns the hash of default headers to sent in all requests

Example:
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

◆ getSendEncoding()

*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:
*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

◆ getSerialization()

string RestClient::RestClient::getSerialization ( )

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

Example:
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()

◆ getValidator()

RestSchemaValidator::AbstractRestSchemaValidator RestClient::RestClient::getValidator ( )

returns the current validator object

Returns
the current validator object
Since
RestClient 1.4

◆ patch()

hash RestClient::RestClient::patch ( string  path,
auto  body,
*reference< hash info,
*hash  hdr 
)

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

Example:
hash ans = rest.patch("/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; if present the hash will contain the following keys:
  • headers: a hash of outgoing HTTP request headers
  • request-uri: the request URI string sent (ex: "PATCH /services/async/38.0/job HTTP/1.1")
  • body-content-type: the outgoing message body Mime Content-Type value
  • response-headers: a hash of incoming HTTP headers in the response
  • chunked: set to True if the response was received with chunked transfer encoding
  • response-code: the HTTP response code
  • response-body: the raw message body in the response (after any content decoding)
  • response-serialization: the type of message serialization in the response; see DataSerializationOptions for possible values when used with the null REST schema validator
  • request-body: the raw message body in the request (before any content encoding)
  • request-serialization: the type of message serialization in the request; see DataSerializationOptions for possible values when used with the null REST schema validator
hdrany 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 deserialized to Qore data and 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-RECEIVE-ERRORif this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
  • "response-code": the HTTP response code given
  • "response-headers": a hash of response headers
  • "response-body": the decoded response body

Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.

See also

◆ post()

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

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

Example:
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; if present the hash will contain the following keys:
  • headers: a hash of outgoing HTTP request headers
  • request-uri: the request URI string sent (ex: "POST /services/async/38.0/job HTTP/1.1")
  • body-content-type: the outgoing message body Mime Content-Type value
  • response-headers: a hash of incoming HTTP headers in the response
  • chunked: set to True if the response was received with chunked transfer encoding
  • response-code: the HTTP response code
  • response-body: the raw message body in the response (after any content decoding)
  • response-serialization: the type of message serialization in the response; see DataSerializationOptions for possible values when used with the null REST schema validator
  • request-body: the raw message body in the request (before any content encoding)
  • request-serialization: the type of message serialization in the request; see DataSerializationOptions for possible values when used with the null REST schema validator
hdrany 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 deserialized to Qore data and 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-RECEIVE-ERRORif this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
  • "response-code": the HTTP response code given
  • "response-headers": a hash of response headers
  • "response-body": the decoded response body

Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.

See also

◆ put()

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

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

Example:
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; if present the hash will contain the following keys:
  • headers: a hash of outgoing HTTP request headers
  • request-uri: the request URI string sent (ex: "PUT /services/async/38.0/job HTTP/1.1")
  • body-content-type: the outgoing message body Mime Content-Type value
  • response-headers: a hash of incoming HTTP headers in the response
  • chunked: set to True if the response was received with chunked transfer encoding
  • response-code: the HTTP response code
  • response-body: the raw message body in the response (after any content decoding)
  • response-serialization: the type of message serialization in the response; see DataSerializationOptions for possible values when used with the null REST schema validator
  • request-body: the raw message body in the request (before any content encoding)
  • request-serialization: the type of message serialization in the request; see DataSerializationOptions for possible values when used with the null REST schema validator
hdrany 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 deserialized to Qore data and 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-RECEIVE-ERRORif this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
  • "response-code": the HTTP response code given
  • "response-headers": a hash of response headers
  • "response-body": the decoded response body

Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.

See also

◆ setContentEncoding()

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
encthe 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-ERRORinvalid or unsupported data content encoding / compression option
See also
Since
RestClient 1.3

◆ setSendEncoding()

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
encthe 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-ERRORinvalid or unsupported data content encoding / compression option
See also

◆ setSerialization()

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

◆ DataSerializationOptions

const RestClient::RestClient::DataSerializationOptions
Initial value:
= (
"auto": True,
"json": True,
"yaml": True,
"rawxml": True,
"xml": True,
"url": True,
"text": 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, rawxml, xml-rpc, url, and text
  • "xml": use only XML-RPC serialization
  • "rawxml": use raw XML serialization
  • "json": use only JSON serialization
  • "yaml": use only YAML serialization
  • "xml": use only XML-RPC serialization
  • "text": use only plain text. No serialization is used.

◆ EncodingSupport

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