Loading...
Searching...
No Matches
RestClient::RestConnection Class Reference

class for REST HTTP connections; returns RestClient::RestClient objects More...

## Public Member Functions

| authFailure ()
| Flags an authorization failure.
| authSuccess ()
| Flags a successful connection.
| clearAltTokenSigner ()
| Clears alt token signer code and the header for it.
| constructor (hash< auto > config, *hash< auto > attr)
| creates the RestConnection connection object
| constructor (string name, string description, string url, hash< auto > attributes={}, hash< auto > options={})
| creates the RestConnection connection object
RestClient | get (bool connect=True, *hash< auto > rtopts)
| returns the underlying connection object
string | getAuthorizationCodeRequest (hash< AuthCodeInfo > info=< AuthCodeInfo >{})
| Returns a URI for an authorization code request.
string | getAuthUrl (*bool allow_relative)
| Returns the OAuth2 authorization URL or throws an exception if not set.
*hash< auto > | getConnectionOptions (*hash< auto > rtopts)
| Returns options for creating a new connection.
DataProvider::AbstractDataProvider | getDataProvider (*hash< auto > constructor_options)
| returns a data provider object for this connection
*LoggerInterface | getLogger ()
| Returns the logger interface for logging.
*hash< auto > | getOAuth2AuthHeaders ()
| Returns headers to use with OAuth2 authorization / token requests.
string | getOAuth2OptionName (string opt)
| Returns the OAuth2 option name for this connection.
hash< auto > | getOAuth2Options ()
| Returns OAuth2 options in a standard format.
hash< auto > | getOptions ()
| gets options
object | getPollImpl ()
| Returns an unconnected object for a non-blocking poll operation.
string | getTokenUrl (*bool allow_relative)
| Returns the OAuth2 token URL or throws an exception if not set.
string | getType ()
| returns `"rest"`
bool | hasDataProvider ()
| returns True, as this connection always returns a data provider with the getDataProvider() method
bool | needsAuth ()
| Returns True if the connection requires OAuth2 authorization before it can be used.
hash< auto > | processOAuth2TokenResponse (hash< auto > resp)
| Processes the OAuth2 token response.
| setAltTokenSigner (code signer, string signer_header)
| Sets alt token signer code and the header for it.
| setLogger (*LoggerInterface logger)
| Accepts a LoggerInterface object for logging (or clears it)
Qore::AbstractPollOperation | startPollConnect (*Logger::LoggerInterface logger)
| Called to start a non-blocking polling ping operation on the remote REST server.

## Static Public Member Functions

static hash< auto > | processOptions (string name, *hash< auto > opts)
| processes options for the constructor

## Public Attributes

const | ConnectionScheme = ...
| Connection entry info.
bool | needs_auth
| Connections needs authorization?
const | OAuth2AuthRequestOptions = ...
| Options required for an OAuth2 authorization request.
const | OAuth2Options = ...
| All OAuth2 options.
const | OptionList = keys ConnectionScheme.options
| object connection option list
const | Options = map {$1: True}
| object connection options
const | RCF_OAUTH2_AUTH_CODE = "oauth2-auth-code"
| RestClient feature: OAuth2 Auth Code support.
hash< auto > | real_opts
| real options used when creating an object

## Protected Member Functions

| checkAuthCodeFeature ()
| Sets the auth code feature if supported.
| checkCanConnect ()
| Checks if the connection can theoretically communicate, if not, sets the connection as down.
hash< ConnectionSchemeInfo > | getConnectionSchemeInfoImpl ()
| Returns the ConnectionSchemeInfo hash for this object.
*hash< string, bool > | getFeaturesImpl ()
| Returns a list of connection-defined features.
RestClient | getImpl (bool connect=True, *hash< auto > rtopts)
| returns a RestClient object
auto | getPingBody ()
| Returns the ping body from the `ping_body` option.
*string | getPingPath ()
| Returns the ping path from the `ping_path` option.
string | getUrlOption (string opt, *bool allow_relative)
| Returns the value of a URL option or throws an exception if not set.
string | getUrlOptionIntern (string uri, *bool allow_relative)
| Returns the value of a URL option.
| pingImpl ()
| performs the internal ping
*hash< auto > | processOAuth2TokenResponseImpl (hash< auto > resp)
| Processes OAuth2 login responses and returns updated options.
| setChildCapabilities ()
| Sets child data provider capabilities.
| setFeatures ()
| Sets features during REST client initialization.
| setupRest ()
| Common REST client initialization.
RestClient | setupRestClientConfig (RestClient rest)
| Sets the alt token signer code and header on a RestClient object if applicable.

## Static Protected Member Functions

static softstring | getUriValue (auto v, string separator=' ')
| Returns a value for use as a URI parameter.

## Protected Attributes

transient *code | alt_token_signer
| To use to sign requests to the any alt token URL.
transient *string | alt_token_signer_header
| The header for the alt token signer.
hash< string, bool > | features
| Hash of supported features.

## Detailed Description

class for REST HTTP connections; returns RestClient::RestClient objects

supports the following options:

- `"connect_timeout"`: connection timeout to use in milliseconds
- `"content_encoding"`: this sets the send encoding (if the `"send_encoding"` option is not set) and the requested response encoding; for possible values, see EncodingSupport
- `"data"`: see RestClient::RestClient::DataSerializationOptions for possible values when used with the null REST schema validator; the default is `"auto"`
- `"error_passthru"`: if True then HTTP status codes indicating errors will not cause a `REST-RESPONSE-ERROR` exception to be raised, rather such responses will be passed through to the caller like any other response
- `"headers"`: an optional hash of headers to send with every request, these can also be overridden in request method calls; also a string giving headers can be given in the format: `header1=value, header2=value`; the value will be parsed with parse_to_qore_value()
- `"http_version"`: HTTP version to use (`"1.0"` or `"1.1"`, defaults to `"1.1"`)
- `"max_redirects"`: maximum redirects to support
- `"oauth2_app"`: An OAuth2 app name for external programs handling OAuth2 calls for this client
- `"oauth2_auth_url"`: The OAuth2 authorization URL for the `authorization_code` grant type; ignored if the `token` option is set. Note that the `authorization_code` grant type requires external user authorization to acquire an access token
- `"oauth2_client_id"`: The OAuth2 client ID; ignored if the `token` option is set
- `"oauth2_client_secret"`: the OAuth2 client secret; ignored if the `token` option is set
- `"oauth2_grant_type"`: the OAuth2 grant type; ignored if the `token` option is set; possible values:
  - `"authorization_code"`: requires `oauth2_client_id`, `oauth2_client_secret`, `oauth2_auth_url`, as well as `oauth2_token_url`; note that this grant type cannot be handled automatically but rather must be handled by external code that redirects the user to the authentication server and then updates the connection with token information retrieved
  - `"client_credentials"`: requires `oauth2_client_id`, `oauth2_client_secret`, as well as `oauth2_token_url`
  - `"password"`: requires a username, password, `oauth2_client_id`, `oauth2_client_secret`, as well as `oauth2_token_url`
  - `"none"`: same as if this option is not set; it means that no OAuth2 grant flow will be used
- `"oauth2_pkce"`: Use PKCE (Proof Key Code Exchange) when using the OAuth2 `authorization_code` flow. Note that this is a hint for external applications processing the flow.
- `"oauth2_redirect_url"`: The OAuth2 redirect URL for the `authorization_code` grant type; ignored if the `token` option is set. Note that the `authorization_code` grant type requires external user authorization to acquire an access token; the special value `"auto"` (the default) is meant to be interpreted by servers that implement OAuth2 authorization code client handling
- `"oauth2_refresh_token"`: An OAuth2 refresh token (complements option `"token"`)
- `"oauth2_scopes"`: A list of OAuth2 scopes to request; ignored if the `token` option is set
- `"oauth2_scope_separator_char"`: A separator character for OAuth2 scopes in URI arguments
- `"oauth2_token_args"`: Extra arguments for OAuth2 authentication requests to `oauth2_token_url`; if this option is set as well as `oauth2_alt_token_url`, then the `oauth2_token_url` value will be added to this as well when the request is made to the `oauth2_alt_token_url`
- `"oauth2_token_expiry"`: The expiry date of the token, if known
- `"oauth2_token_expiry_hint"`: A integer value in minutes giving the expected lifetime of the token
- `"oauth2_token_url"`: The token URL for OAuth2 flows; ignored if the `token` option is set
- `"password"`: The password for authentication; only used if no username or password is set in the URL and if the `username` option is also used
- `"proxy"`: proxy URL to use
- `"redirect_passthru"`: if True then redirect responses wil0l be passed to the caller instead of processed
- `"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
- `"swagger"`: the path to a Swagger 2.0 REST schema file for runtime API validation (see the Swagger module); conflicts with validator
- `"swagger_base_path"`: in case a REST validator is used, the base path in the schema can be overridden with this option (applies to any REST validator; not just Swagger validators)
- `"swagger_lax_parsing"`: try to parse invalid Swagger schemas
- `"timeout"`: transfer timeout to use in milliseconds
- `"token"`: Any bearer token to use for the connection; will be passed as `Authorization: Bearer ...` in request headers; cannot be used with username and password options or authentication information in the URL; if this option is set then any OAuth2 options are ignored
- `"token_api_key_header"`: The name of a header where to send the token as an API key
- `"username"`: The username for authentication; only used if no username or password is set in the URL
- `"validator"`: an AbstractRestSchemaValidator object to validate request and response messages; conflicts with swagger

Note
  additionally supports the following runtime option in getImpl():
  - `"validator"`: an AbstractRestSchemaValidator object for REST message validation (if present, overrides any REST schema validation option provided as a connection option)

See also
  RestClient::constructor() for more information on the above options

Since
  RestConnection 1.4

## Member Function Documentation

## authFailure()

RestClient::RestConnection::authFailure | ( |  | ) |

Flags an authorization failure.

Since
  RestClient 2.2

## authSuccess()

RestClient::RestConnection::authSuccess | ( |  | ) |

Flags a successful connection.

Since
  RestClient 2.2

## checkCanConnect()

RestClient::RestConnection::checkCanConnect | ( |  | ) |

protected

Checks if the connection can theoretically communicate, if not, sets the connection as down.

Connections are assumed to be up when created; this method call is made during constructor initialization and should set the `up` flag to False and set the `status` key appropriately in case the connection has an incomplete or invalid configuration

Since
  RestClient 2.2.0

## clearAltTokenSigner()

RestClient::RestConnection::clearAltTokenSigner | ( |  | ) |

Clears alt token signer code and the header for it.

Since
  RestClient 2.2

## constructor() [1/2]

RestClient::RestConnection::constructor | ( | hash< auto > | config,
|  | *hash< auto > | attr )

creates the RestConnection connection object

Parameters

  config

  with the following keys:
  - name (required string): the connection name
  - display_name (optional string): the display name
  - short_desc (optional string): a short description in plain text
  - desc (optional string): a long description with markdown formatting
  - url (required string): the connection URL
  - opts (optional hash): connection options
  - logger (optional LoggerInterface object): logger for the connection

  attr

  optional connection attributes
  - monitor (optional bool): should the connection be monitored? Default: True
  - enabled (optional bool): is the connection enabled? Default: True
  - locked (optional bool): is the connection locked? Default: False
  - debug_data (optional bool): debug data? Default: False
  - tags (optional hash): tags for the connection; no default value

Exceptions

  CONNECTION-OPTION-ERROR | missing or invalid connection option or attribute

## constructor() [2/2]

RestClient::RestConnection::constructor | ( | string | name,
|  | string | description,
|  | string | url,
|  | hash< auto > | attributes = {},
|  | hash< auto > | options = {} )

creates the RestConnection connection object

Parameters

  name | the name of the connection
  description | connection description
  url | connection URL (potentially with password info)
  attributes | various attributes. See below
  options | connection options; see class documentation for information on supported options

See AbstractConnection::constructor() for `attributes` and `options` reference.

Additional Attributes
  - `error` a custom error string

Exceptions

  CONNECTION-OPTION-ERROR | missing or invalid connection option

## get()

RestClient RestClient::RestConnection::get | ( | bool | connect = True,
|  | *hash< auto > | rtopts )

returns the underlying connection object

calls getImpl() to actually acquire the connection object

## getAuthorizationCodeRequest()

string RestClient::RestConnection::getAuthorizationCodeRequest | ( | hash< AuthCodeInfo > | info = < AuthCodeInfo >{} | ) |

Returns a URI for an authorization code request.

The `oauth2_grant_type` must be `authorization_code`, and `oauth2_client_id`, `oauth2_auth_url`, `oauth2_redirect_url` must set if the `redirect_uri` option is not used

Parameters

  info | context information for the authorization code request

Since
  RestClient 2.0

## getDataProvider()

DataProvider::AbstractDataProvider RestClient::RestConnection::getDataProvider | ( | *hash< auto > | constructor_options | ) |

returns a data provider object for this connection

Parameters

  constructor_options | any additional constructor options for the data provider

Returns
  a data provider object for this connection; the data provider is:
  - `SwaggerDataProvider:` if an appropriate schema is configured
  - `RestClientDataProvider:` if there is no schema configured

Exceptions

  DATA-PROVIDER-ERROR | this object does not support the data provider API

## getFeaturesImpl()

*hash< string, bool > RestClient::RestConnection::getFeaturesImpl | ( |  | ) |

protected

Returns a list of connection-defined features.

Since
  RestClient 2.0

## getImpl()

RestClient RestClient::RestConnection::getImpl | ( | bool | connect = True,
|  | *hash< auto > | rtopts )

protected

returns a RestClient object

Parameters

  connect | if True, then the connection is returned already connected

  rtopts

  supports the following runtime option in getImpl():
  - `"validator"`: an AbstractRestSchemaValidator object for REST message validation (if present, overrides any REST schema validation option provided as a connection option)

Returns
  a RestClient object

## getOAuth2AuthHeaders()

*hash< auto > RestClient::RestConnection::getOAuth2AuthHeaders | ( |  | ) |

Returns headers to use with OAuth2 authorization / token requests.

Since
  RestClient 2.2

## getOAuth2OptionName()

string RestClient::RestConnection::getOAuth2OptionName | ( | string | opt | ) |

Returns the OAuth2 option name for this connection.

Since
  RestClient 2.0

## getOAuth2Options()

hash< auto > RestClient::RestConnection::getOAuth2Options | ( |  | ) |

Returns OAuth2 options in a standard format.

Since
  RestClient 2.0

## getOptions()

hash< auto > RestClient::RestConnection::getOptions | ( |  | ) |

gets options

Returns
  returns a hash with supported options

See also
  class documentation for information on supported options

## getPollImpl()

object RestClient::RestConnection::getPollImpl | ( |  | ) |

Returns an unconnected object for a non-blocking poll operation.

Returns
  an unconnected object for a non-blocking poll operation

Since
  RestClient 1.9.1

## hasDataProvider()

bool RestClient::RestConnection::hasDataProvider | ( |  | ) |

returns True, as this connection always returns a data provider with the getDataProvider() method

Returns
  True, as this connection always returns a data provider with the getDataProvider() method

See also
  getDataProvider()

## needsAuth()

bool RestClient::RestConnection::needsAuth | ( |  | ) |

Returns True if the connection requires OAuth2 authorization before it can be used.

Returns
  True if the connection requires OAuth2 authorization, False if already authorized, or the connection does not support authorization

Since
  RestClient 2.2

## pingImpl()

RestClient::RestConnection::pingImpl | ( |  | ) |

protected

performs the internal ping

Uses the ping options to make a request to the server

## processOAuth2TokenResponse()

hash< auto > RestClient::RestConnection::processOAuth2TokenResponse | ( | hash< auto > | resp | ) |

Processes the OAuth2 token response.

Since
  RestClient 2.0

## processOptions()

static hash< auto > RestClient::RestConnection::processOptions | ( | string | name,
|  | *hash< auto > | opts )

static

processes options for the constructor

In particular it parses any string as a value of the `"headers"` option to return a hash

## setAltTokenSigner()

RestClient::RestConnection::setAltTokenSigner | ( | code | signer,
|  | string | signer_header )

Sets alt token signer code and the header for it.

Since
  RestClient 2.2

## setFeatures()

RestClient::RestConnection::setFeatures | ( |  | ) |

protected

Sets features during REST client initialization.

Since
  RestClient 2.2.0

## setupRest()

RestClient::RestConnection::setupRest | ( |  | ) |

protected

Common REST client initialization.

Since
  RestClient 2.2.0

## setupRestClientConfig()

RestClient RestClient::RestConnection::setupRestClientConfig | ( | RestClient | rest | ) |

protected

Sets the alt token signer code and header on a RestClient object if applicable.

Parameters

  rest | the RestClient object to set the alt token signer on

Since
  RestClient 2.2

## startPollConnect()

Qore::AbstractPollOperation RestClient::RestConnection::startPollConnect | ( | *Logger::LoggerInterface | logger | ) |

Called to start a non-blocking polling ping operation on the remote REST server.

Returns
  a socket poll operation object that will allow the connection goal to be reached with polling

See also
  supportsPollingApi()

## Member Data Documentation

## RCF_OAUTH2_AUTH_CODE

const RestClient::RestConnection::RCF_OAUTH2_AUTH_CODE = "oauth2-auth-code"

RestClient feature: OAuth2 Auth Code support.

Returned as a connection feature if the connection is configured for the oauth2 authorization_code grant flow