All Classes Namespaces Functions Variables Groups Pages
RestClient::RestClient Class Reference

this class provides the REST client API More...

Inheritance diagram for RestClient::RestClient:
[legend]

## 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...
private | decodeError (hash h, *reference info)
| decode any REST errors returned if possible
| 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=True, *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...
hash | sendAndDecodeResponse (*data body, string m, string path, hash hdr, *reference 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 | 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:
  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:
  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)

  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:
  - `"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
  - RestClient::getSerialization()
  - RestClient::setSerialization()

hash RestClient::RestClient::doRequest | ( | string | m,
|  | string | path,
|  | any | body,
|  | *reference | 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

  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

  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:
  - `"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
  - RestClient::getSerialization()
  - RestClient::setSerialization()

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

  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:
  - `"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
  - RestClient::getSerialization()
  - RestClient::setSerialization()

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

*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
  - RestClient::setContentEncoding()
  - RestClient::setSendEncoding()

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

  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:
  - `"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
  - RestClient::getSerialization()
  - RestClient::setSerialization()

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

  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:
  - `"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
  - RestClient::getSerialization()
  - RestClient::setSerialization()

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
  - RestClient::getSendEncoding()
  - RestClient::setSendEncoding()

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::setContentEncoding()
  - RestClient::getSendEncoding()

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