RestClient::RestConnection Class Reference

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

#include <RestClient.qm.dox.h>

Inheritance diagram for RestClient::RestConnection:

Public Member Methods
	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 Methods
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

Private Member Methods
	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 Private Member Methods
static softstring	getUriValue (auto v, string separator=' ')
	Returns a value for use as a URI parameter.

Private 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 ( )

private

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

private

Returns a list of connection-defined features.

Since

RestClient 2.0

getImpl()

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

private

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

private

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

private

Sets features during REST client initialization.

Since

RestClient 2.2.0

setupRest()

RestClient::RestConnection::setupRest ( )

private

Common REST client initialization.

Since

RestClient 2.2.0

setupRestClientConfig()

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

private

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