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

| 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

  opts

  valid 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_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

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

  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

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

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

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

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

  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

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

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

  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

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

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

  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

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

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