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
	constructor (string name, string description, string url, hash< auto > attributes={}, hash< auto > options={})
	creates the RestConnection connection object More...
string	getAuthorizationCodeRequest (hash< AuthCodeInfo > info=< AuthCodeInfo >{})
	Returns a URI for an authorization code request. More...
string	getAuthUrl (*bool allow_relative)
	Returns the OAuth2 authorization URL or throws an exception if not set.
DataProvider::AbstractDataProvider	getDataProvider ()
	returns a data provider object for this connection More...
string	getOAuth2OptionName (string opt)
	Returns the OAuth2 option name for this connection. More...
hash< auto >	getOAuth2Options ()
	Returns OAuth2 options in a standard format. More...
hash< auto >	getOptions ()
	gets options More...
object	getPollImpl ()
	Returns an unconnected object for a non-blocking poll operation. More...
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 More...
hash< auto >	processOAuth2TokenResponse (hash< auto > resp)
	Processes the OAuth2 token response. More...
Qore::AbstractPollOperation	startPollConnect ()
	Called to start a non-blocking polling ping operation on the remote REST server. More...

Static Public Member Methods
static hash< auto >	processOptions (*hash< auto > opts)
	processes options for the constructor More...

Public Attributes
const	ConnectionScheme
	Connection entry info.
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. More...
hash< auto >	real_opts
	real options used when creating an object

Private Member Methods
	checkAuthCodeFeature ()
	Sets the auth code feature if supported.
hash< ConnectionSchemeInfo >	getConnectionSchemeInfoImpl ()
	Returns the ConnectionSchemeInfo hash for this object.
*hash< string, bool >	getFeaturesImpl ()
	Returns a list of connection-defined features. More...
RestClient	getImpl (bool connect=True, *hash< auto > rtopts)
	returns a RestClient object More...
string	getUrlOption (string opt, *bool allow_relative)
	Returns the value of a URL option or throws an exception if not set.
	pingImpl ()
	performs the internal ping More...
*hash< auto >	processOAuth2TokenResponseImpl (hash< auto > resp)
	Processes OAuth2 login responses and returns updated options.
	setChildCapabilities ()
	Sets child data provider capabilities.

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_auth_args": Extra arguments for OAuth2 authentication requests to oauth2_auth_url for the authentication_code grant type. Note that the authorization_code grant type requires external user authorization to acquire an access token
• "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
• "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_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 and if the password option is also used
• "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

constructor()

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

(

)

returns a data provider object for this connection

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  )

privatevirtual

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

Implements ConnectionProvider::AbstractConnection.

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

pingImpl()

RestClient::RestConnection::pingImpl ( )

private

performs the internal ping

By default this creates a new connection only; override in child classes to implement additional ping logic

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

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