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.

	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

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

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

	setLogger (*LoggerInterface logger)
	Accepts a LoggerInterface object for logging (or clears it)

Qore::AbstractPollOperation	startPollConnect ()
	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.

Static Private Member Methods
static softstring	getUriValue (auto v)
	Returns a value for use as a URI parameter.

Private Attributes
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_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_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
"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

◆ 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

◆ 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

◆ 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

◆ startPollConnect()

Qore::AbstractPollOperation RestClient::RestConnection::startPollConnect ( )

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

Public Member Methods

Static Public Member Methods

Public Attributes

Private Member Methods

Static Private Member Methods

Private Attributes

Detailed Description

Member Function Documentation

◆ authFailure()

◆ authSuccess()

◆ checkCanConnect()

◆ constructor() [1/2]

◆ constructor() [2/2]

◆ getAuthorizationCodeRequest()

◆ getDataProvider()

◆ getFeaturesImpl()

◆ getImpl()

◆ getOAuth2AuthHeaders()

◆ getOAuth2OptionName()

◆ getOAuth2Options()

◆ getOptions()

◆ getPollImpl()

◆ hasDataProvider()

◆ needsAuth()

◆ pingImpl()

◆ processOAuth2TokenResponse()

◆ processOptions()

◆ setFeatures()

◆ setupRest()

◆ startPollConnect()

Member Data Documentation

◆ RCF_OAUTH2_AUTH_CODE