![]() |
Qore RestClient Module Reference 2.3.0
|
this class provides the REST client API More...
Public Member Functions | |
| addDefaultHeaders (hash< auto > h) | |
| adds default headers to each request | |
| clearAltTokenSigner () | |
| Clears alt token signer code and the header for it. | |
| clearConnectionPath () | |
| Clears the connection path when a validator is present that manages the URI path. | |
| constructor (*hash< auto > opts, *softbool do_not_connect) | |
| calls the base class HTTPClient constructor and optionally connects to the REST server | |
| hash< auto > | del (string path, auto body, *reference< hash< auto > > info, *hash< auto > hdr) |
sends an HTTP DELETE request to the REST server and returns the response | |
| hash< auto > | doRequest (string m, string path, auto body, *reference< hash< auto > > info, softbool decode_errors=True, *hash< auto > hdr) |
| sends an HTTP request to the REST server and returns the response | |
| hash< auto > | doSignedRequest (string shdr, code signer, string m, string path, auto body, *reference< hash< auto > > info, softbool decode_errors=True, *hash< auto > hdr) |
| sends a signed HTTP request to the REST server and returns the response | |
| hash< auto > | doValidatedRequest (string m, string path, auto body, *reference< hash< auto > > info, softbool decode_errors=True, *hash< auto > hdr) |
| The same as doRequest() except no schema validation is performed on the request. | |
| hash< auto > | get (string path, auto body, *reference< hash< auto > > info, *hash< auto > hdr) |
sends an HTTP GET request to the REST server and returns the response | |
| hash< auto > | getDefaultHeaders () |
| returns the hash of default headers to sent in all requests | |
| *LoggerInterface | getLogger () |
| Returns the logger interface for logging. | |
| hash< auto > | getNewToken () |
| Get a new token from the server either with an OAuth2 token request or using the refresh token. | |
| hash< auto > | getOAuth2Options () |
| Return OAuth2 options. | |
| *string | getSendEncoding () |
| returns the current data content encoding (compression) object or nothing if no encoding option is set | |
| string | getSerialization () |
| returns the current data serialization format currently in effect for the object | |
| *string | getToken () |
| Returns any token set for the connection. | |
| string | getTokenType () |
| Returns the token type for any token. | |
| RestSchemaValidator::AbstractRestSchemaValidator | getValidator () |
| returns the current validator object | |
| hash< auto > | gotOAuth2LoginInfo (hash< auto > h, *bool refresh) |
| Called when OAuth2 login information has been received. | |
| bool | isAuthTokenError (int status_code, hash< auto > headers, *bool body_deserialized, *string body_content_type, auto body) |
| Returns True if the response was related to an authorization token error. | |
| bool | needsRestBodyAuthErrorCheck () |
| Returns True if the object needs to have deserialized bodies check for authentication errors. | |
| hash< auto > | patch (string path, auto body, *reference< hash< auto > > info, *hash< auto > hdr) |
sends an HTTP PATCH request to the REST server and returns the response | |
| hash< auto > | post (string path, auto body, *reference< hash< auto > > info, *hash< auto > hdr) |
sends an HTTP POST request to the REST server and returns the response | |
| prepareToSend (string method, reference< string > path, reference< auto > body, *reference< hash< auto > > hdr) | |
| Prepares and processes message parameters for sending without sending the message. | |
| auto | preprocessRequestBody (auto request_body) |
| Preprocesses the request body before serialization. | |
| hash< auto > | processRestResponse (hash< auto > resp, string method, string path, *reference< hash< auto > > info) |
| Process the raw REST response received. | |
| hash< auto > | put (string path, auto body, *reference< hash< auto > > info, *hash< auto > hdr) |
sends an HTTP PUT request to the REST server and returns the response | |
| replaceDefaultHeaders (*hash< auto > hdr) | |
| replaces default headers | |
| bool | requiresOAuth2Token () |
| Returns True if the client requires an OAuth2 token. | |
| bool | requiresRefresh () |
| Returns True if the client requires a tokenm refresh. | |
| setAltTokenSigner (code signer, string signer_header) | |
| Sets alt token signer code and the header for it. | |
| setContentEncoding (string enc='auto') | |
| sets the request and desired response encoding for the object; see EncodingSupport for valid options | |
| setLogger (*LoggerInterface logger) | |
| Accepts a LoggerInterface object for logging (or clears it) | |
| setOAuth2Options (hash< auto > new_opts) | |
| Sets OAuth2 options. | |
| setSendEncoding (string enc='auto') | |
| change the data content encoding (compression) option for the object | |
| setSerialization (string data='auto') | |
| change the serialization option for the object; see DataSerializationOptions for valid options | |
| setToken (string token_type, string token, *string refresh_token, *date token_expiry) | |
| Sets a token for authentication. | |
| setupUserPassword (hash< auto > opts) | |
| Setup username and password consistently. | |
| setValidator (RestSchemaValidator::AbstractRestSchemaValidator validator) | |
| Sets a new REST schema validator. | |
| AbstractPollOperation | startOAuth2PollRefreshToken () |
| Starts an OAuth2 refresh token request in a non-blocking I/O operation. | |
| AbstractPollOperation | startOAuth2PollSendRecv () |
| Starts an OAuth2 token request in a non-blocking I/O operation. | |
| AbstractPollOperation | startPollCustomGetToken () |
| Starts a custom token refresh request in a non-blocking I/O operation. | |
| bool | usingOAuth2 () |
| Returns True if the client is configured for authentication with OAuth2. | |
Static Public Member Functions | |
| static *string | getScopeString (*list< auto > scopes, string separator=' ') |
| Returns a scope string URI argument. | |
Public Attributes | |
| const | Accept = AcceptList.join(",") |
| Accept header value. | |
| const | AcceptList = ... |
| Accept header list. | |
| const | AcceptMap = map {$1: True} |
| Map of acceptable Mime types. | |
| const | CompressionThreshold = 1024 |
| default threadhold for data compressions; transfers smaller than this size will not be compressed | |
| const | CustomTokenOptions = ... |
| Custom token options; if at least one is set, they all must be set. | |
| const | DataSerializationOptions = ... |
| Data serialization options; this is a hash to simulate a set of strings. | |
| 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 | DefaultOAuth2RedirectUrl = "auto" |
| Default oauth2_redirect_url option value. | |
| const | DefaultOptions = ... |
| Default option values. | |
| const | EncodingSupport = ... |
| Send content encoding options. | |
| const | MinimumTokenRefresh = 1m |
| Minimum time between OAuth2 token requests. | |
| const | OAuth2AuthHeaders = ... |
| Headers to send when making an authorization / token request. | |
| const | OAuth2GrantOptions = ... |
| Option requirements per OAuth2 grant type. | |
| const | Oauth2TokenRefreshWindow = 10m |
| Refresh a new token 10 minutes before it expires. | |
| const | Version = "2.2" |
| RestClient Version. | |
| const | VersionString = sprintf("Qore-RestClient/%s", RestClient::Version) |
| RestClient Version String. | |
Protected Member Functions | |
| checkLogin (*reference< hash< auto > > info) | |
| Checks if a login is necessary; if so, then the login is performed. | |
| checkOAuth2Options (hash< auto > opts, *bool no_exceptions) | |
| Validates and sets any OAuth2 options. | |
| hash< auto > | customGetTokenIntern (*reference< hash< auto > > info, *bool refresh) |
| Gets a new token using the custom token refresh method. | |
| hash< auto > | doOAuth2LoginRequest (string url, hash< auto > login, *reference< hash< auto > > info, *string real_url) |
| Returns the deserialized response body of an OAuth2 authorization / token request. | |
| hash< auto > | doRequestIntern (string m, string path, auto body, *reference< hash< auto > > info, softbool decode_errors=True, *hash< auto > hdr, *string assume_content_type, *string shdr, *code signer) |
| Makes a REST request and returns the result. | |
| hash< auto > | getNewTokenIntern (*reference< hash< auto > > info) |
| Get a new token from the server. | |
| *hash< auto > | getOAuth2AuthHeaders () |
| Returns headers to use with OAuth2 authorization / token requests. | |
| hash< auto > | getOAuth2LoginInfo (string grant_type) |
| Returns an OAuth2 login hash. | |
| hash< auto > | getOAuth2RefreshInfo () |
| Returns an OAuth2 refresh hash. | |
| *hash< auto > | getUpdateOptionsAfterLogin (hash< auto > h, *bool refresh) |
| Returns options to update after an OAuth2 login. | |
| hash< auto > | loginIntern (*reference< hash< auto > > info) |
| Authenticates with OAuth2 or a custom token method if configured. | |
| bool | needsRefresh (*hash< ExceptionInfo > ex, *hash< auto > info, *bool body_deserialized, auto body) |
| Returns True if the request error indicates that a refresh operation should be performed. | |
| hash< auto > | oauth2Auth (hash< auto > login, *reference< hash< auto > > info, *bool refresh) |
| Perform OAuth2 authentication. | |
| hash< auto > | oauth2AuthIntern (hash< auto > login, *reference< hash< auto > > info, *bool refresh) |
| Perform OAuth2 authentication. | |
| nothing | prepareMsg (string method, string path, reference< auto > body, reference< hash< auto > > hdr, string ct='Content-Type') |
| sets up the Content-Type header and encodes any body for sending | |
| nothing | preparePath (reference< string > path) |
| sets up the path for the HTTP request URI | |
| hash< auto > | refreshTokenIntern (*reference< hash< auto > > info) |
| Gets a new token using the refresh token. | |
| hash< auto > | sendAndDecodeResponse (*data body, string m, string path, hash< auto > hdr, *reference< hash< auto > > info, *softbool decode_errors, *string assume_content_type, *string shdr, *code signer) |
| sends the outgoing HTTP message and recodes the response to data | |
| setOAuth2LoginInfo (hash< auto > h) | |
| Sets options from the OAuth2 login response on the local object. | |
| setupAuth (hash< auto > opts, *bool no_exceptions) | |
| Sets up authentication info. | |
| *hash< auto > | setupCustomGetToken (reference< hash< auto > > auth_hdr) |
| Sets up a custom token refresh request. | |
| AbstractPollOperation | startOAuth2AuthPoll (hash< auto > login) |
| Starts a non-blocking I/O operation to authenticate with an OAuth2 server and acquire an auth token. | |
Static Protected Member Functions | |
| static | decodeError (hash< auto > h, *reference< hash< auto > > info) |
| decode any REST errors returned if possible | |
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. | |
| string | custom_token_auth |
| REST custom token auth method. | |
| string | custom_token_location |
| REST custom token location. | |
| string | custom_token_method |
| REST custom refresh HTTP method. | |
| string | custom_token_path |
| REST custom refresh URI path. | |
| string | oauth2_alt_token_url |
| Alternate OAuth2 token URL. | |
| *hash< auto > | oauth2_alt_url_subst |
| Alternate OAuth2 URL substitution info. | |
| string | oauth2_app |
| OAuth2 app name. | |
| *hash< auto > | oauth2_auth_args |
| OAuth2 extra auth args. | |
| string | oauth2_auth_url |
| OAuth2 auth URL. | |
| bool | oauth2_auto_refresh = True |
| If OAuth2 tokens should be automatically refreshed. | |
| string | oauth2_client_id |
| OAuth2 client ID. | |
| string | oauth2_client_secret |
| OAuth2 client secret. | |
| string | oauth2_grant_type |
| OAuth2 grant type. | |
| bool | oauth2_pkce = False |
| If PKCE should be used with the OAuth2 authorization_code flow. | |
| string | oauth2_redirect_url |
| OAuth2 redirect URL. | |
| string | oauth2_scope_separator_char |
| OAuth2 scope separator char. | |
| *softlist< string > | oauth2_scopes |
| OAuth2 scope. | |
| *hash< auto > | oauth2_token_args |
| OAuth2 extra token args. | |
| bool | oauth2_token_auth_secret_only = False |
| If HTTP basic authentication should be used with the client_secret only when making token requests. | |
| date | oauth2_token_expiry |
| The token expiry date. | |
| int | oauth2_token_expiry_hint |
| An expiry date hint as a value in minutes. | |
| string | oauth2_token_url |
| OAuth2 token URL. | |
| bool | oauth2_token_use_basic_auth = False |
| If HTTP basic authentication should be used with the client_id and client_secret when making token requests. | |
| string | password |
| password for authentication | |
| string | refresh_token |
| Any refresh token granted to the client. | |
| *hash< auto > | rest_body_auth_error_check |
| A hash to check all deserialized bodies in 200 OK server responses for authentication errors. | |
| string | token |
| Any token set for the connection; will be passed as a bearer token (Authorization: Bearer ...) | |
| string | token_api_key_header |
| If this option is set along with a token, it indicates a header to send the token in as an API key. | |
| date | token_timestamp |
| Last timestamp for token acquisition. | |
| string | token_type |
| The token type, if any. | |
| string | username |
| username for authentication | |
Static Private Member Functions | |
| static | tryDecodeErrorResponse (reference< hash< auto > > h, *reference< hash< auto > > info) |
| tries to decode an error response | |
this class provides the REST client API
| RestClient::RestClient::addDefaultHeaders | ( | hash< auto > | h | ) |
adds default headers to each request
| h | a hash of headers to add to the default headers to send on each request |
Headers added here will be sent in all requests but can be overridden in requests as well.
|
protected |
Validates and sets any OAuth2 options.
| RestClient::RestClient::clearAltTokenSigner | ( | ) |
Clears alt token signer code and the header for it.
| RestClient::RestClient::clearConnectionPath | ( | ) |
Clears the connection path when a validator is present that manages the URI path.
Called from the constructor when a REST validator is present that manages the URI path
| RestClient::RestClient::constructor | ( | *hash< auto > | opts, |
| *softbool | do_not_connect ) |
calls the base class HTTPClient constructor and optionally connects to the REST server
| opts | valid options are:
|
url: A string giving the URL to connect to; if not given then the target URL will be taken from any validator option, if given by calling AbstractRestSchemaValidator::getTargetUrl()username: The username for authentication; only used if no username or password is set in the URL and if the password option is also usedvalidator: an AbstractRestSchemaValidator object to validate request and response messages; overrides swagger no_charset: if True no charset will be added to the Content-Type header | do_not_connect | if False (the default), then a connection will be immediately established to the remote server |
| RESTCLIENT-ERROR | invalid option passed to constructor, unsupported data serialization, etc |
|
protected |
Gets a new token using the custom token refresh method.
| hash< auto > RestClient::RestClient::del | ( | string | path, |
| auto | body, | ||
| *reference< hash< auto > > | info, | ||
| *hash< auto > | hdr ) |
sends an HTTP DELETE request to the REST server and returns the response
| 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; see rest-info-format for information about the structure of the hash written to the reference supplied here |
| hdr | any headers to be sent with the request; headers here will override default headers for the object as well |
"body" key| DESERIALIZATION-ERROR | the response body could not be deserialized (unknown Content-Type or invalid serialization) |
| REST-RESPONSE-ERROR | if this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
error_passthru option is set to True |
Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.
|
protected |
Returns the deserialized response body of an OAuth2 authorization / token request.
| hash< auto > RestClient::RestClient::doRequest | ( | string | m, |
| string | path, | ||
| auto | body, | ||
| *reference< hash< auto > > | info, | ||
| softbool | decode_errors = True, | ||
| *hash< auto > | hdr ) |
sends an HTTP request to the REST server and returns the response
| 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; see rest-info-format for information about the structure of the hash written to the reference supplied here |
| 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; headers here will override default headers for the object as well |
"body" key| DESERIALIZATION-ERROR | the response body could not be deserialized (unknown Content-Type or invalid serialization) |
| HTTP-CLIENT-METHOD-ERROR | invalid HTTP method argument passed |
| REST-RESPONSE-ERROR | if this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
error_passthru option is set to True |
| REST-ACCEPT-ERROR | if the message has a validator that indicates that the response message only supports types not supported by the current options or environment |
Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.
| hash< auto > RestClient::RestClient::doSignedRequest | ( | string | shdr, |
| code | signer, | ||
| string | m, | ||
| string | path, | ||
| auto | body, | ||
| *reference< hash< auto > > | info, | ||
| softbool | decode_errors = True, | ||
| *hash< auto > | hdr ) |
sends a signed HTTP request to the REST server and returns the response
| shdr | the name of the header that will have the signature |
| signer | the code that will return a signature string to put in the header identified by shdr, the argument to this closure will be a hash with the following keys:
|
| 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; see rest-info-format for information about the structure of the hash written to the reference supplied here |
| 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; headers here will override default headers for the object as well |
"body" key| DESERIALIZATION-ERROR | the response body could not be deserialized (unknown Content-Type or invalid serialization) |
| HTTP-CLIENT-METHOD-ERROR | invalid HTTP method argument passed |
| REST-RESPONSE-ERROR | if this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
error_passthru option is set to True |
| REST-ACCEPT-ERROR | if the message has a validator that indicates that the response message only supports types not supported by the current options or environment |
Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.
| hash< auto > RestClient::RestClient::doValidatedRequest | ( | string | m, |
| string | path, | ||
| auto | body, | ||
| *reference< hash< auto > > | info, | ||
| softbool | decode_errors = True, | ||
| *hash< auto > | hdr ) |
The same as doRequest() except no schema validation is performed on the request.
| hash< auto > RestClient::RestClient::get | ( | string | path, |
| auto | body, | ||
| *reference< hash< auto > > | info, | ||
| *hash< auto > | hdr ) |
sends an HTTP GET request to the REST server and returns the response
| 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(); note that sending a message body with an HTTP GET request is not standards compliant; see httpclient_get_with_body for more information; for maximum compatibility, use nothing for this argument when calling this method |
| 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; see rest-info-format for information about the structure of the hash written to the reference supplied here |
| hdr | any headers to be sent with the request; headers here will override default headers for the object as well |
"body" key| DESERIALIZATION-ERROR | the response body could not be deserialized (unknown Content-Type or invalid serialization) |
| REST-RESPONSE-ERROR | if this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
error_passthru option is set to True |
Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.
| hash< auto > RestClient::RestClient::getDefaultHeaders | ( | ) |
returns the hash of default headers to sent in all requests
| hash< auto > RestClient::RestClient::getNewToken | ( | ) |
Get a new token from the server either with an OAuth2 token request or using the refresh token.
| AUTH-CONFIG-ERROR | The RestClient is not configured for token retrieval |
The \ oauth2_grant_type option must be set on the client, or an exception will be thrown
| AUTH-CONFIG-ERROR | cannot retrieve an OAuth2 token without OAuth2 option configuration |
|
protected |
Get a new token from the server.
|
protected |
Returns headers to use with OAuth2 authorization / token requests.
|
protected |
Returns an OAuth2 login hash.
| hash< auto > RestClient::RestClient::getOAuth2Options | ( | ) |
|
protected |
Returns an OAuth2 refresh hash.
|
static |
Returns a scope string URI argument.
| scopes | the list of scopes to use |
| separator | the separator string to use |
| *string RestClient::RestClient::getSendEncoding | ( | ) |
returns the current data content encoding (compression) object or nothing if no encoding option is set
| string RestClient::RestClient::getSerialization | ( | ) |
returns the current data serialization format currently in effect for the object
| *string RestClient::RestClient::getToken | ( | ) |
Returns any token set for the connection.
| string RestClient::RestClient::getTokenType | ( | ) |
Returns the token type for any token.
|
protected |
Returns options to update after an OAuth2 login.
| RestSchemaValidator::AbstractRestSchemaValidator RestClient::RestClient::getValidator | ( | ) |
returns the current validator object
| hash< auto > RestClient::RestClient::gotOAuth2LoginInfo | ( | hash< auto > | h, |
| *bool | refresh ) |
Called when OAuth2 login information has been received.
@bool refresh used to distinguish an initial login or new information from a token refresh
| bool RestClient::RestClient::isAuthTokenError | ( | int | status_code, |
| hash< auto > | headers, | ||
| *bool | body_deserialized, | ||
| *string | body_content_type, | ||
| auto | body ) |
Returns True if the response was related to an authorization token error.
|
protected |
Authenticates with OAuth2 or a custom token method if configured.
|
protected |
Perform OAuth2 authentication.
|
protected |
Perform OAuth2 authentication.
| hash< auto > RestClient::RestClient::patch | ( | string | path, |
| auto | body, | ||
| *reference< hash< auto > > | info, | ||
| *hash< auto > | hdr ) |
sends an HTTP PATCH request to the REST server and returns the response
| 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; see rest-info-format for information about the structure of the hash written to the reference supplied here |
| hdr | any headers to be sent with the request; headers here will override default headers for the object as well |
"body" key| DESERIALIZATION-ERROR | the response body could not be deserialized (unknown Content-Type or invalid serialization) |
| REST-RESPONSE-ERROR | if this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
error_passthru option is set to True |
Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.
| hash< auto > RestClient::RestClient::post | ( | string | path, |
| auto | body, | ||
| *reference< hash< auto > > | info, | ||
| *hash< auto > | hdr ) |
sends an HTTP POST request to the REST server and returns the response
| 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; see rest-info-format for information about the structure of the hash written to the reference supplied here |
| hdr | any headers to be sent with the request; headers here will override default headers for the object as well |
"body" key| DESERIALIZATION-ERROR | the response body could not be deserialized (unknown Content-Type or invalid serialization) |
| REST-RESPONSE-ERROR | if this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
error_passthru option is set to True |
Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.
| RestClient::RestClient::prepareToSend | ( | string | method, |
| reference< string > | path, | ||
| reference< auto > | body, | ||
| *reference< hash< auto > > | hdr ) |
Prepares and processes message parameters for sending without sending the message.
| method | the HTTP method to use @path a reference to the URI path @path body a reference to any message body @path hdr a reference to any headers to send |
| auto RestClient::RestClient::preprocessRequestBody | ( | auto | request_body | ) |
Preprocesses the request body before serialization.
The default is to return the request body unchanged
| hash< auto > RestClient::RestClient::processRestResponse | ( | hash< auto > | resp, |
| string | method, | ||
| string | path, | ||
| *reference< hash< auto > > | info ) |
Process the raw REST response received.
| resp | the return value from HTTPClient::send() |
| method | the HTTP method used |
| path | the URI path used |
| info | an optional info hash reference for information about the call |
| hash< auto > RestClient::RestClient::put | ( | string | path, |
| auto | body, | ||
| *reference< hash< auto > > | info, | ||
| *hash< auto > | hdr ) |
sends an HTTP PUT request to the REST server and returns the response
| 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; see rest-info-format for information about the structure of the hash written to the reference supplied here |
| hdr | any headers to be sent with the request; headers here will override default headers for the object as well |
"body" key| DESERIALIZATION-ERROR | the response body could not be deserialized (unknown Content-Type or invalid serialization) |
| REST-RESPONSE-ERROR | if this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
error_passthru option is set to True |
Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.
|
protected |
Gets a new token using the refresh token.
| RestClient::RestClient::replaceDefaultHeaders | ( | *hash< auto > | hdr | ) |
replaces default headers
| hdr | The headers to set; DefaultHeaders will be added to this hash to set the default headers for the object |
| bool RestClient::RestClient::requiresOAuth2Token | ( | ) |
Returns True if the client requires an OAuth2 token.
| bool RestClient::RestClient::requiresRefresh | ( | ) |
Returns True if the client requires a tokenm refresh.
| RestClient::RestClient::setAltTokenSigner | ( | code | signer, |
| string | signer_header ) |
Sets alt token signer code and the header for it.
| RestClient::RestClient::setContentEncoding | ( | string | enc = 'auto' | ) |
sets the request and desired response encoding for the object; see EncodingSupport for valid options
| enc | the data content encoding (compression) option for requests and the desired response content encoding for the object; see EncodingSupport for valid options; if the value "auto" is passed then "gzip" encoding is used for outgoing requests and requested for responses |
| RESTCLIENT-ERROR | invalid or unsupported data content encoding / compression option |
|
protected |
Sets options from the OAuth2 login response on the local object.
| RestClient::RestClient::setOAuth2Options | ( | hash< auto > | new_opts | ) |
| RestClient::RestClient::setSendEncoding | ( | string | enc = 'auto' | ) |
change the data content encoding (compression) option for the object
The default is to send requests unencoded/uncompressed.
| enc | the data content encoding (compression) option for the object; see EncodingSupport for valid options; if the value "auto" is passed then "gzip" encoding is used |
| RESTCLIENT-ERROR | invalid or unsupported data content encoding / compression option |
| RestClient::RestClient::setSerialization | ( | string | data = 'auto' | ) |
change the serialization option for the object; see DataSerializationOptions for valid options
| data | the serialization option for the object; see DataSerializationOptions for valid options |
| RESTCLIENT-ERROR | invalid or unsupported serialization option |
| RestClient::RestClient::setToken | ( | string | token_type, |
| string | token, | ||
| *string | refresh_token, | ||
| *date | token_expiry ) |
Sets a token for authentication.
|
protected |
Sets up authentication info.
|
protected |
Sets up a custom token refresh request.
| RestClient::RestClient::setValidator | ( | RestSchemaValidator::AbstractRestSchemaValidator | validator | ) |
Sets a new REST schema validator.
|
protected |
Starts a non-blocking I/O operation to authenticate with an OAuth2 server and acquire an auth token.
| AbstractPollOperation RestClient::RestClient::startOAuth2PollRefreshToken | ( | ) |
Starts an OAuth2 refresh token request in a non-blocking I/O operation.
| AbstractPollOperation RestClient::RestClient::startOAuth2PollSendRecv | ( | ) |
Starts an OAuth2 token request in a non-blocking I/O operation.
| AbstractPollOperation RestClient::RestClient::startPollCustomGetToken | ( | ) |
Starts a custom token refresh request in a non-blocking I/O operation.
| bool RestClient::RestClient::usingOAuth2 | ( | ) |
Returns True if the client is configured for authentication with OAuth2.
|
protected |
REST custom token auth method.
allowed values:
|
protected |
REST custom token location.
allowed values:
| const RestClient::RestClient::DataSerializationOptions = ... |
Data serialization options; this is a hash to simulate a set of strings.
Data serialization options are as follows:
"auto": prefers in this order: json, yaml, rawxml, xml, url, and text"bin": for binary message bodies without data serialization"json": use only JSON serialization"rawxml": use raw XML serialization"text": use only plain text. No serialization is used."url": for URL-encoded message bodies"xml": use only XML-RPC serialization"yaml": use only YAML serialization | const RestClient::RestClient::EncodingSupport = ... |
Send content encoding options.
Send content encoding options are as follows:
"bzip": use bzip2 compression"gzip": use gzip compression"deflate": use deflate compression"identity": use no content encoding
|
protected |
OAuth2 app name.
To be used by external programs handling OAuth2 calls for this client
|
protected |
If PKCE should be used with the OAuth2 authorization_code flow.
To be used by external programs handling OAuth2 calls for this client
| const RestClient::RestClient::OAuth2GrantOptions = ... |
Option requirements per OAuth2 grant type.
authorization_code grant type cannot be handled automatically