|
Qore RestClient Module Reference
1.4.1
|
this class provides the REST client API More...

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 | |
this class provides the REST client API
| 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
| h | a hash of headers to add to the default headers to send on each request |
| RestClient::RestClient::constructor | ( | *hash | opts, |
| *softbool | do_not_connect | ||
| ) |
calls the base class HTTPClient constructor and optionally connects to the REST server
| opts | valid options are:
|
| do_not_connect | if False (the default), then a connection will be immediately established to the remote server |
| RESTCLIENT-ERROR | invalid option passed to constructor, unsupported data serialization, etc |
sends an HTTP DELETE request to the REST server and returns the response
| 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; if present the hash will contain the following keys:
|
| hdr | any headers to be sent with the request; headers here will override default headers for the object as well |
"body" key| DESERIALIZATION-ERROR | the response body could not be deserialized (unknown Content-Type or invalid serialization) |
| HTTP-CLIENT-RECEIVE-ERROR | if 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:
|
Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.
| 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
| 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; if present the hash will contain the following keys:
|
| 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 |
"body" key| DESERIALIZATION-ERROR | the response body could not be deserialized (unknown Content-Type or invalid serialization) |
| HTTP-CLIENT-METHOD-ERROR | invalid HTTP method argument passed |
| HTTP-CLIENT-RECEIVE-ERROR | if 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:
|
Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.
sends an HTTP GET request to the REST server and returns the response
| 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(); note that sending a message body with an HTTP GET request is not standards compliant; see httpclient_get_with_body for more information; for maximum compatibility, use NOTHING for this argument when calling this method |
| 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; if present the hash will contain the following keys:
|
| hdr | any headers to be sent with the request; headers here will override default headers for the object as well |
"body" key| DESERIALIZATION-ERROR | the response body could not be deserialized (unknown Content-Type or invalid serialization) |
| HTTP-CLIENT-RECEIVE-ERROR | if 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:
|
Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.
| hash RestClient::RestClient::getDefaultHeaders | ( | ) |
returns the hash of default headers to sent in all requests
| *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
| string RestClient::RestClient::getSerialization | ( | ) |
returns the current data serialization format currently in effect for the object (see DataSerializationOptions for possible values)
| RestSchemaValidator::AbstractRestSchemaValidator RestClient::RestClient::getValidator | ( | ) |
returns the current validator object
sends an HTTP PATCH request to the REST server and returns the response
| 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; if present the hash will contain the following keys:
|
| hdr | any headers to be sent with the request; headers here will override default headers for the object as well |
"body" key| DESERIALIZATION-ERROR | the response body could not be deserialized (unknown Content-Type or invalid serialization) |
| HTTP-CLIENT-RECEIVE-ERROR | if 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:
|
Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.
sends an HTTP POST request to the REST server and returns the response
| 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; if present the hash will contain the following keys:
|
| hdr | any headers to be sent with the request; headers here will override default headers for the object as well |
"body" key| DESERIALIZATION-ERROR | the response body could not be deserialized (unknown Content-Type or invalid serialization) |
| HTTP-CLIENT-RECEIVE-ERROR | if 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:
|
Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.
sends an HTTP PUT request to the REST server and returns the response
| 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; if present the hash will contain the following keys:
|
| hdr | any headers to be sent with the request; headers here will override default headers for the object as well |
"body" key| DESERIALIZATION-ERROR | the response body could not be deserialized (unknown Content-Type or invalid serialization) |
| HTTP-CLIENT-RECEIVE-ERROR | if 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:
|
Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.
| RestClient::RestClient::setContentEncoding | ( | string | enc = "auto" | ) |
sets the request and desired response encoding for the object; see EncodingSupport for valid options
| 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 |
| RESTCLIENT-ERROR | invalid or unsupported data content encoding / compression option |
| RestClient::RestClient::setSendEncoding | ( | string | enc = "auto" | ) |
change the data content encoding (compression) option for the object; see EncodingSupport for valid options
The default is to send requests unencoded/uncompressed.
| 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 |
| RESTCLIENT-ERROR | invalid or unsupported data content encoding / compression option |
| RestClient::RestClient::setSerialization | ( | string | data = "auto" | ) |
change the serialization option for the object; see DataSerializationOptions for valid options
| data | the serialization option for the object; see DataSerializationOptions for valid options |
| RESTCLIENT-ERROR | invalid or unsupported serialization option |
| const RestClient::RestClient::DataSerializationOptions |
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."bin": for binary message bodies without data serialization | const RestClient::RestClient::EncodingSupport |
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