Qore RestClient Module Reference 2.3.0
Loading...
Searching...
No Matches
RestClient.qm.dox.h
1// -*- mode: c++; indent-tabs-mode: nil -*-
3
4/* RestClient.qm Copyright (C) 2013 - 2024 Qore Technologies, s.r.o.
5
6 Permission is hereby granted, free of charge, to any person obtaining a
7 copy of this software and associated documentation files (the "Software"),
8 to deal in the Software without restriction, including without limitation
9 the rights to use, copy, modify, merge, publish, distribute, sublicense,
10 and/or sell copies of the Software, and to permit persons to whom the
11 Software is furnished to do so, subject to the following conditions:
12
13 The above copyright notice and this permission notice shall be included in
14 all copies or substantial portions of the Software.
15
16 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22 DEALINGS IN THE SOFTWARE.
23*/
24
25// minimum qore version
26
27// require type definitions everywhere
28
29// enable all warnings
30
31// don't use "$" for vars, members, and methods, assume local variable scope
32
33
34
35
36
37
38
39/* Version History - see below in docs
40*/
41
273namespace RestClient {
275
277public hashdecl AuthCodeInfo {
279 string response_type = "code";
280
283
285 *list<string> scopes;
286
288 *string state;
289};
290
293
294public:
296 const DataSerializationSupport = ...;
297
298
299 const DeserializeYaml = ...;
300
301 const DeserializeXml = ...;
302
303
305 const AcceptList = ...;
306
307
309 const Accept = AcceptList.join(",");
310
312 const AcceptMap = map {$1: True}, AcceptList;
313
315 const Version = "2.2";
316
318 const VersionString = sprintf("Qore-RestClient/%s", RestClient::Version);
319
321 const DefaultHeaders = ...;
322
323
325 const DefaultOAuth2RedirectUrl = "auto";
326
328 const DefaultOptions = ...;
329
330
332
342 const DataSerializationOptions = ...;
343
344
346
352 const EncodingSupport = ...;
353
354
356 const CompressionThreshold = 1024;
357
359
361 const OAuth2GrantOptions = ...;
362
363
365 const OAuth2AuthHeaders = ...;
366
367
369 const MinimumTokenRefresh = 1m;
370
372 const Oauth2TokenRefreshWindow = 10m;
373
375 const CustomTokenOptions = ...;
376
377
378protected:
379 // headers to send with every request
380 hash<auto> headers;
381 // data serialization code
382 string ds;
383 // serialization content type
384 string sct;
385 // send content encoding hash
386 *hash<auto> seh;
387 // REST schema validator
389 // no_charset option
390 *bool noCharset;
391
393 string username;
395 string password;
396
404 *softlist<string> oauth2_scopes;
408 *hash<auto> oauth2_auth_args;
410 *hash<auto> oauth2_token_args;
424 string token;
430 bool oauth2_auto_refresh = True;
432 bool oauth2_token_auth_secret_only = False;
434 bool oauth2_token_use_basic_auth = False;
440
442 bool oauth2_pkce = False;
444
451
453
458
467
469 transient *code alt_token_signer;
471 transient *string alt_token_signer_header;
472
473public:
474
476
589 constructor(*hash<auto> opts, *softbool do_not_connect) ;
590
591
593 setLogger(*LoggerInterface logger);
594
595
598
599
601
605 setOAuth2Options(hash<auto> new_opts);
606
607
609
613 hash<auto> getOAuth2Options();
614
615
617
620
621
623
636 setSerialization(string data = 'auto');
637
638
640
657 setSendEncoding(string enc = 'auto');
658
659
661
678 setContentEncoding(string enc = 'auto');
679
680
682
698 addDefaultHeaders(hash<auto> h);
699
700
702
715 hash<auto> getDefaultHeaders();
716
717
719
724 replaceDefaultHeaders(*hash<auto> hdr);
725
726
728
744
745
747
760
761
763
805 hash<auto> get(string path, auto body, *reference<hash<auto>> info, *hash<auto> hdr);
806
807
809
848 hash<auto> put(string path, auto body, *reference<hash<auto>> info, *hash<auto> hdr);
849
850
852
891 hash<auto> patch(string path, auto body, *reference<hash<auto>> info, *hash<auto> hdr);
892
893
895
934 hash<auto> post(string path, auto body, *reference<hash<auto>> info, *hash<auto> hdr);
935
936
938
977 hash<auto> del(string path, auto body, *reference<hash<auto>> info, *hash<auto> hdr);
978
979
981
986
987
989
992
993
995
998
999
1001
1004
1005
1007
1010
1011
1013
1015 setToken(string token_type, string token, *string refresh_token, *date token_expiry);
1016
1017
1019
1022
1023
1025
1027 *string getToken();
1028
1029
1031
1033 AbstractPollOperation startOAuth2PollSendRecv();
1034
1035
1037
1039 AbstractPollOperation startPollCustomGetToken();
1040
1041
1043
1045 AbstractPollOperation startOAuth2PollRefreshToken();
1046
1047
1049
1096 hash<auto> doRequest(string m, string path, auto body, *reference<hash<auto>> info, softbool decode_errors = True, *hash<auto> hdr);
1097
1098
1100
1153 hash<auto> doSignedRequest(string shdr, code signer, string m, string path, auto body, *reference<hash<auto>> info, softbool decode_errors = True, *hash<auto> hdr);
1154
1155
1157protected:
1158 bool needsRefresh(*hash<ExceptionInfo> ex, *hash<auto> info, *bool body_deserialized, auto body);
1159public:
1160
1161
1163
1167 bool isAuthTokenError(int status_code, hash<auto> headers, *bool body_deserialized, *string body_content_type, auto body);
1168
1169
1171
1181 hash<auto> getNewToken();
1182
1183
1185
1187protected:
1188 *hash<auto> setupCustomGetToken(reference<hash<auto>> auth_hdr);
1189public:
1190
1191
1193
1196protected:
1197 hash<auto> getNewTokenIntern(*reference<hash<auto>> info);
1198public:
1199
1200
1202
1206protected:
1207 hash<auto> customGetTokenIntern(*reference<hash<auto>> info, *bool refresh);
1208public:
1209
1210
1212
1216protected:
1217 hash<auto> refreshTokenIntern(*reference<hash<auto>> info);
1218public:
1219
1220
1222protected:
1223 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);
1224public:
1225
1226
1228
1235 prepareToSend(string method, reference<string> path, reference<auto> body, *reference<hash<auto>> hdr);
1236
1237
1239
1241 hash<auto> doValidatedRequest(string m, string path, auto body, *reference<hash<auto>> info, softbool decode_errors = True, *hash<auto> hdr);
1242
1243
1245
1252 hash<auto> processRestResponse(hash<auto> resp, string method, string path, *reference<hash<auto>> info);
1253
1254
1256
1260 hash<auto> gotOAuth2LoginInfo(hash<auto> h, *bool refresh);
1261
1262
1264
1268 auto preprocessRequestBody(auto request_body);
1269
1270
1272 *LoggerInterface getLogger();
1273
1274
1276
1281 static *string getScopeString(*list<auto> scopes, string separator = ' ');
1282
1284
1286 setAltTokenSigner(code signer, string signer_header);
1287
1288
1290
1293
1294
1296
1298protected:
1299 setOAuth2LoginInfo(hash<auto> h);
1300public:
1301
1302
1304
1306protected:
1307 *hash<auto> getUpdateOptionsAfterLogin(hash<auto> h, *bool refresh);
1308public:
1309
1310
1312
1314protected:
1315 setupAuth(hash<auto> opts, *bool no_exceptions);
1316public:
1317
1318
1320 setupUserPassword(hash<auto> opts);
1321
1322
1324
1326protected:
1327 checkOAuth2Options(hash<auto> opts, *bool no_exceptions);
1328public:
1329
1330
1332
1334protected:
1335 hash<auto> loginIntern(*reference<hash<auto>> info);
1336public:
1337
1338
1340
1342protected:
1343 AbstractPollOperation startOAuth2AuthPoll(hash<auto> login);
1344public:
1345
1346
1348
1350protected:
1351 hash<auto> oauth2Auth(hash<auto> login, *reference<hash<auto>> info, *bool refresh);
1352public:
1353
1354
1356
1358protected:
1359 hash<auto> oauth2AuthIntern(hash<auto> login, *reference<hash<auto>> info, *bool refresh);
1360public:
1361
1362
1364
1366protected:
1367 hash<auto> doOAuth2LoginRequest(string url, hash<auto> login, *reference<hash<auto>> info, *string real_url);
1368public:
1369
1370
1372
1374protected:
1376public:
1377
1378
1380
1382protected:
1383 hash<auto> getOAuth2LoginInfo(string grant_type);
1384public:
1385
1386
1388
1390protected:
1392public:
1393
1394
1396protected:
1397 nothing prepareMsg(string method, string path, reference<auto> body, reference<hash<auto>> hdr, string ct = 'Content-Type');
1398public:
1399
1400
1402protected:
1403 nothing preparePath(reference<string> path);
1404public:
1405
1406
1408protected:
1409 checkLogin(*reference<hash<auto>> info);
1410public:
1411
1412
1414protected:
1415 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);
1416public:
1417
1418
1420protected:
1421 static decodeError(hash<auto> h, *reference<hash<auto>> info);
1422public:
1423
1424
1426private:
1427 static tryDecodeErrorResponse(reference<hash<auto>> h, *reference<hash<auto>> info);
1428public:
1429
1430}; // class RestClient
1431
1433
1513
1514public:
1516 hash<auto> real_opts;
1517
1520
1522 const ConnectionScheme = ...;
1523
1524
1526 const Options = map {$1: True}, keys ConnectionScheme.options;
1527
1529 const OptionList = keys ConnectionScheme.options;
1530
1533
1534
1536 const OAuth2Options = ...;
1537
1538
1540
1543 const RCF_OAUTH2_AUTH_CODE = "oauth2-auth-code";
1544
1545protected:
1547 transient *code alt_token_signer;
1549 transient *string alt_token_signer_header;
1550
1552 hash<string, bool> features = {
1553 CF_LOGGER: True,
1554 };
1555
1556public:
1557
1559
1572 constructor(string name, string description, string url, hash<auto> attributes = {}, hash<auto> options = {})
1573 ;
1574
1575
1577
1594 constructor(hash<auto> config, *hash<auto> attr) ;
1595
1596
1598 setLogger(*LoggerInterface logger);
1599
1600
1602 *LoggerInterface getLogger();
1603
1604
1606
1612
1613
1615
1619
1620
1622
1626
1627
1629
1631 string getOAuth2OptionName(string opt);
1632
1633
1635
1639 object getPollImpl();
1640
1641
1643
1647 hash<auto> getOptions();
1648
1649
1651 string getType();
1652
1653
1655
1657 hash<auto> getOAuth2Options();
1658
1659
1661
1663 hash<auto> processOAuth2TokenResponse(hash<auto> resp);
1664
1665
1667
1670
1671
1673
1681 DataProvider::AbstractDataProvider getDataProvider(*hash<auto> constructor_options);
1682
1683
1685
1690
1691
1693
1698 Qore::AbstractPollOperation startPollConnect(*Logger::LoggerInterface logger);
1699
1700
1702
1704 static hash<auto> processOptions(string name, *hash<auto> opts);
1705
1707
1714 string getAuthorizationCodeRequest(hash<AuthCodeInfo> info = <AuthCodeInfo>{});
1715
1716
1718 /* @param allow_relative if @ref True then a relative URL (path only) can be returned; the default (@ref False)
1719 is to return a full URL
1720
1721 @since %RestClient 2.0
1722 */
1723 string getAuthUrl(*bool allow_relative);
1724
1725
1727 /* @param allow_relative if @ref True then a relative URL (path only) can be returned; the default (@ref False)
1728 is to return a full URL
1729
1730 @since %RestClient 2.0
1731 */
1732 string getTokenUrl(*bool allow_relative);
1733
1734
1736 *hash<auto> getConnectionOptions(*hash<auto> rtopts);
1737
1738
1740
1742 setAltTokenSigner(code signer, string signer_header);
1743
1744
1746
1749
1750
1752
1754 RestClient get(bool connect = True, *hash<auto> rtopts);
1755
1756
1758
1760protected:
1762public:
1763
1764
1766
1768protected:
1770public:
1771
1772
1774
1780protected:
1782public:
1783
1784
1786 /* @param opt the URL option name
1787 @param allow_relative if @ref True then a relative URL (path only) can be returned; the default (@ref False)
1788 is to return a full URL
1789
1790 @since %RestClient 2.1.1
1791 */
1792protected:
1793 string getUrlOption(string opt, *bool allow_relative);
1794public:
1795
1796
1798 /* @param uri the URL value
1799 @param allow_relative if @ref True then a relative URL (path only) can be returned; the default (@ref False)
1800 is to return a full URL
1801
1802 @since %RestClient 2.2
1803 */
1804protected:
1805 string getUrlOptionIntern(string uri, *bool allow_relative);
1806public:
1807
1808
1810 /*
1811 @since %RestClient 2.0
1812 */
1813protected:
1814 static softstring getUriValue(auto v, string separator = ' ');
1815public:
1816
1817
1819protected:
1820 *hash<auto> processOAuth2TokenResponseImpl(hash<auto> resp);
1821public:
1822
1823
1825protected:
1827public:
1828
1829
1831
1839protected:
1840 RestClient getImpl(bool connect = True, *hash<auto> rtopts);
1841public:
1842
1843
1845
1848protected:
1850public:
1851
1852
1854
1856protected:
1858public:
1859
1860
1862protected:
1863 *string getPingPath();
1864public:
1865
1866
1868protected:
1870public:
1871
1872
1874
1876protected:
1877 *hash<string, bool> getFeaturesImpl();
1878public:
1879
1880
1882protected:
1884public:
1885
1886
1888protected:
1889 hash<ConnectionSchemeInfo> getConnectionSchemeInfoImpl();
1890public:
1891
1892};
1893
1895
1898
1899public:
1901 const SPS_GET_SWAGGER = 'get-swagger';
1902
1904 const SPS_OAUTH2_GET_TOKEN = "oauth2-get-token";
1905
1907 const SPS_OAUTH2_REFRESH_TOKEN = "oauth2-refresh-token";
1908
1910 const SPS_CUSTOM_GET_TOKEN = "custom-refresh";
1911
1913 const SPS_REST_PING = "rest-ping";
1914
1916 const SPS_COMPLETE = "complete";
1917
1918protected:
1921
1924
1926 hash<auto> real_opts;
1927
1929 AbstractPollOperation poller;
1930
1932 bool goal_reached = False;
1933
1935 string method;
1936
1938 string path;
1939
1941 *auto body;
1942
1944 *hash<auto> headers;
1945
1947 string state;
1948
1950 Mutex m();
1951
1954
1957
1958public:
1959
1962
1963
1966
1967
1969
1971 string getGoal();
1972
1973
1975
1977 string getState();
1978
1979
1981
1984
1985
1987 *hash<SocketPollInfo> continuePoll();
1988
1989
1990 abort();
1991
1992
1993protected:
1994 checkOtherStates();
1995public:
1996
1997
1998protected:
1999 gotOAuth2LoginInfo(hash<auto> h);
2000public:
2001
2002
2003protected:
2004 doStartGetToken();
2005public:
2006
2007
2008protected:
2009 doStartRefresh();
2010public:
2011
2012
2013protected:
2014 doStartPing();
2015public:
2016
2017
2018protected:
2019 checkUrl();
2020public:
2021
2022};
2023};
bool requiresRefresh()
Returns True if the client requires a tokenm refresh.
string oauth2_scope_separator_char
OAuth2 scope separator char.
Definition RestClient.qm.dox.h:406
auto preprocessRequestBody(auto request_body)
Preprocesses the request body before serialization.
hash< auto > oauth2AuthIntern(hash< auto > login, *reference< hash< auto > > info, *bool refresh)
Perform OAuth2 authentication.
*string getToken()
Returns any token set for the connection.
string oauth2_app
OAuth2 app name.
Definition RestClient.qm.dox.h:446
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.
Definition RestClient.qm.dox.h:428
checkOAuth2Options(hash< auto > opts, *bool no_exceptions)
Validates and sets any OAuth2 options.
string custom_token_path
REST custom refresh URI path.
Definition RestClient.qm.dox.h:466
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
bool usingOAuth2()
Returns True if the client is configured for authentication with OAuth2.
*hash< auto > getUpdateOptionsAfterLogin(hash< auto > h, *bool refresh)
Returns options to update after an OAuth2 login.
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.
string custom_token_method
REST custom refresh HTTP method.
Definition RestClient.qm.dox.h:464
hash< auto > getNewToken()
Get a new token from the server either with an OAuth2 token request or using the refresh token.
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
static tryDecodeErrorResponse(reference< hash< auto > > h, *reference< hash< auto > > info)
tries to decode an error response
string oauth2_grant_type
OAuth2 grant type.
Definition RestClient.qm.dox.h:398
string oauth2_redirect_url
OAuth2 redirect URL.
Definition RestClient.qm.dox.h:414
hash< auto > loginIntern(*reference< hash< auto > > info)
Authenticates with OAuth2 or a custom token method if configured.
constructor(*hash< auto > opts, *softbool do_not_connect)
calls the base class HTTPClient constructor and optionally connects to the REST server
transient *code alt_token_signer
To use to sign requests to the any alt token URL.
Definition RestClient.qm.dox.h:469
string token
Any token set for the connection; will be passed as a bearer token (Authorization: Bearer ....
Definition RestClient.qm.dox.h:424
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
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
date oauth2_token_expiry
The token expiry date.
Definition RestClient.qm.dox.h:438
transient *string alt_token_signer_header
The header for the alt token signer.
Definition RestClient.qm.dox.h:471
setupUserPassword(hash< auto > opts)
Setup username and password consistently.
*LoggerInterface getLogger()
Returns the logger interface for logging.
setContentEncoding(string enc='auto')
sets the request and desired response encoding for the object; see EncodingSupport for valid options
hash< auto > getNewTokenIntern(*reference< hash< auto > > info)
Get a new token from the server.
AbstractPollOperation startPollCustomGetToken()
Starts a custom token refresh request in a non-blocking I/O operation.
string oauth2_token_url
OAuth2 token URL.
Definition RestClient.qm.dox.h:416
nothing preparePath(reference< string > path)
sets up the path for the HTTP request URI
setupAuth(hash< auto > opts, *bool no_exceptions)
Sets up authentication info.
hash< auto > getDefaultHeaders()
returns the hash of default headers to sent in all requests
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
setOAuth2LoginInfo(hash< auto > h)
Sets options from the OAuth2 login response on the local object.
setToken(string token_type, string token, *string refresh_token, *date token_expiry)
Sets a token for authentication.
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.
clearAltTokenSigner()
Clears alt token signer code and the header for it.
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.
string getTokenType()
Returns the token type for any token.
hash< auto > refreshTokenIntern(*reference< hash< auto > > info)
Gets a new token using the refresh token.
setLogger(*LoggerInterface logger)
Accepts a LoggerInterface object for logging (or clears it)
hash< auto > getOAuth2RefreshInfo()
Returns an OAuth2 refresh hash.
checkLogin(*reference< hash< auto > > info)
Checks if a login is necessary; if so, then the login is performed.
*hash< auto > setupCustomGetToken(reference< hash< auto > > auth_hdr)
Sets up a custom token refresh request.
string oauth2_client_id
OAuth2 client ID.
Definition RestClient.qm.dox.h:400
*hash< auto > oauth2_alt_url_subst
Alternate OAuth2 URL substitution info.
Definition RestClient.qm.dox.h:418
bool requiresOAuth2Token()
Returns True if the client requires an OAuth2 token.
string oauth2_client_secret
OAuth2 client secret.
Definition RestClient.qm.dox.h:402
bool needsRestBodyAuthErrorCheck()
Returns True if the object needs to have deserialized bodies check for authentication errors.
string token_type
The token type, if any.
Definition RestClient.qm.dox.h:422
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
RestSchemaValidator::AbstractRestSchemaValidator getValidator()
returns the current validator object
int oauth2_token_expiry_hint
An expiry date hint as a value in minutes.
Definition RestClient.qm.dox.h:436
setSerialization(string data='auto')
change the serialization option for the object; see DataSerializationOptions for valid options
clearConnectionPath()
Clears the connection path when a validator is present that manages the URI path.
string oauth2_alt_token_url
Alternate OAuth2 token URL.
Definition RestClient.qm.dox.h:420
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.
setSendEncoding(string enc='auto')
change the data content encoding (compression) option for the object
*hash< auto > oauth2_token_args
OAuth2 extra token args.
Definition RestClient.qm.dox.h:410
hash< auto > oauth2Auth(hash< auto > login, *reference< hash< auto > > info, *bool refresh)
Perform OAuth2 authentication.
static decodeError(hash< auto > h, *reference< hash< auto > > info)
decode any REST errors returned if possible
hash< auto > getOAuth2LoginInfo(string grant_type)
Returns an OAuth2 login hash.
setOAuth2Options(hash< auto > new_opts)
Sets OAuth2 options.
AbstractPollOperation startOAuth2AuthPoll(hash< auto > login)
Starts a non-blocking I/O operation to authenticate with an OAuth2 server and acquire an auth token.
AbstractPollOperation startOAuth2PollRefreshToken()
Starts an OAuth2 refresh token request in a non-blocking I/O operation.
hash< auto > processRestResponse(hash< auto > resp, string method, string path, *reference< hash< auto > > info)
Process the raw REST response received.
hash< auto > getOAuth2Options()
Return OAuth2 options.
*hash< auto > rest_body_auth_error_check
A hash to check all deserialized bodies in 200 OK server responses for authentication errors.
Definition RestClient.qm.dox.h:448
*softlist< string > oauth2_scopes
OAuth2 scope.
Definition RestClient.qm.dox.h:404
replaceDefaultHeaders(*hash< auto > hdr)
replaces default headers
setAltTokenSigner(code signer, string signer_header)
Sets alt token signer code and the header for it.
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.
static *string getScopeString(*list< auto > scopes, string separator=' ')
Returns a scope string URI argument.
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
string password
password for authentication
Definition RestClient.qm.dox.h:395
addDefaultHeaders(hash< auto > h)
adds default headers to each request
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
*hash< auto > getOAuth2AuthHeaders()
Returns headers to use with OAuth2 authorization / token requests.
AbstractPollOperation startOAuth2PollSendRecv()
Starts an OAuth2 token request in a non-blocking I/O operation.
*hash< auto > oauth2_auth_args
OAuth2 extra auth args.
Definition RestClient.qm.dox.h:408
string getSerialization()
returns the current data serialization format currently in effect for the object
hash< auto > gotOAuth2LoginInfo(hash< auto > h, *bool refresh)
Called when OAuth2 login information has been received.
*string getSendEncoding()
returns the current data content encoding (compression) object or NOTHING if no encoding option is se...
const Version
RestClient Version.
Definition RestClient.qm.dox.h:315
string oauth2_auth_url
OAuth2 auth URL.
Definition RestClient.qm.dox.h:412
string refresh_token
Any refresh token granted to the client.
Definition RestClient.qm.dox.h:426
string custom_token_location
REST custom token location.
Definition RestClient.qm.dox.h:462
string username
username for authentication
Definition RestClient.qm.dox.h:393
prepareToSend(string method, reference< string > path, reference< auto > body, *reference< hash< auto > > hdr)
Prepares and processes message parameters for sending without sending the message.
date token_timestamp
Last timestamp for token acquisition.
Definition RestClient.qm.dox.h:450
string custom_token_auth
REST custom token auth method.
Definition RestClient.qm.dox.h:456
hash< auto > customGetTokenIntern(*reference< hash< auto > > info, *bool refresh)
Gets a new token using the custom token refresh method.
setValidator(RestSchemaValidator::AbstractRestSchemaValidator validator)
Sets a new REST schema validator.
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
class for REST HTTP connections; returns RestClient::RestClient objects
Definition RestClient.qm.dox.h:1512
bool hasDataProvider()
returns True, as this connection always returns a data provider with the getDataProvider() method
authSuccess()
Flags a successful connection.
transient *string alt_token_signer_header
The header for the alt token signer.
Definition RestClient.qm.dox.h:1549
string getOAuth2OptionName(string opt)
Returns the OAuth2 option name for this connection.
pingImpl()
performs the internal ping
const OptionList
object connection option list
Definition RestClient.qm.dox.h:1529
constructor(string name, string description, string url, hash< auto > attributes={}, hash< auto > options={})
creates the RestConnection connection object
string getUrlOption(string opt, *bool allow_relative)
Returns the value of a URL option or throws an exception if not set.
hash< auto > real_opts
real options used when creating an object
Definition RestClient.qm.dox.h:1516
setLogger(*LoggerInterface logger)
Accepts a LoggerInterface object for logging (or clears it)
RestClient get(bool connect=True, *hash< auto > rtopts)
returns the underlying connection object
Qore::AbstractPollOperation startPollConnect(*Logger::LoggerInterface logger)
Called to start a non-blocking polling ping operation on the remote REST server.
const Options
object connection options
Definition RestClient.qm.dox.h:1526
*string getPingPath()
Returns the ping path from the ping_path option.
*hash< auto > getConnectionOptions(*hash< auto > rtopts)
Returns options for creating a new connection.
hash< auto > getOAuth2Options()
Returns OAuth2 options in a standard format.
*hash< auto > processOAuth2TokenResponseImpl(hash< auto > resp)
Processes OAuth2 login responses and returns updated options.
string getAuthorizationCodeRequest(hash< AuthCodeInfo > info=< AuthCodeInfo >{})
Returns a URI for an authorization code request.
auto getPingBody()
Returns the ping body from the ping_body option.
const OAuth2AuthRequestOptions
Options required for an OAuth2 authorization request.
Definition RestClient.qm.dox.h:1532
bool needs_auth
Connections needs authorization?
Definition RestClient.qm.dox.h:1519
RestClient setupRestClientConfig(RestClient rest)
Sets the alt token signer code and header on a RestClient object if applicable.
hash< ConnectionSchemeInfo > getConnectionSchemeInfoImpl()
Returns the ConnectionSchemeInfo hash for this object.
DataProvider::AbstractDataProvider getDataProvider(*hash< auto > constructor_options)
returns a data provider object for this connection
bool needsAuth()
Returns True if the connection requires OAuth2 authorization before it can be used.
checkCanConnect()
Checks if the connection can theoretically communicate, if not, sets the connection as down.
checkAuthCodeFeature()
Sets the auth code feature if supported.
string getAuthUrl(*bool allow_relative)
Returns the OAuth2 authorization URL or throws an exception if not set.
object getPollImpl()
Returns an unconnected object for a non-blocking poll operation.
transient *code alt_token_signer
To use to sign requests to the any alt token URL.
Definition RestClient.qm.dox.h:1547
*hash< string, bool > getFeaturesImpl()
Returns a list of connection-defined features.
static hash< auto > processOptions(string name, *hash< auto > opts)
processes options for the constructor
const RCF_OAUTH2_AUTH_CODE
RestClient feature: OAuth2 Auth Code support.
Definition RestClient.qm.dox.h:1543
hash< auto > processOAuth2TokenResponse(hash< auto > resp)
Processes the OAuth2 token response.
string getUrlOptionIntern(string uri, *bool allow_relative)
Returns the value of a URL option.
setChildCapabilities()
Sets child data provider capabilities.
*hash< auto > getOAuth2AuthHeaders()
Returns headers to use with OAuth2 authorization / token requests.
RestClient getImpl(bool connect=True, *hash< auto > rtopts)
returns a RestClient object
setFeatures()
Sets features during REST client initialization.
authFailure()
Flags an authorization failure.
setupRest()
Common REST client initialization.
hash< auto > getOptions()
gets options
const OAuth2Options
All OAuth2 options.
Definition RestClient.qm.dox.h:1536
clearAltTokenSigner()
Clears alt token signer code and the header for it.
const ConnectionScheme
Connection entry info.
Definition RestClient.qm.dox.h:1522
setAltTokenSigner(code signer, string signer_header)
Sets alt token signer code and the header for it.
*LoggerInterface getLogger()
Returns the logger interface for logging.
hash< string, bool > features
Hash of supported features.
Definition RestClient.qm.dox.h:1552
static softstring getUriValue(auto v, string separator=' ')
Returns a value for use as a URI parameter.
string getType()
returns "rest"
string getTokenUrl(*bool allow_relative)
Returns the OAuth2 token URL or throws an exception if not set.
constructor(hash< auto > config, *hash< auto > attr)
creates the RestConnection connection object
REST ping polling I/O class with OAuth2 authentication.
Definition RestClient.qm.dox.h:1897
const SPS_OAUTH2_REFRESH_TOKEN
OAuth2 refresh token state.
Definition RestClient.qm.dox.h:1907
*hash< SocketPollInfo > continuePoll()
Returns a hash to be used for I/O polling or NOTHING in case the poll operation is complete.
bool in_refresh
token refresh flag
Definition RestClient.qm.dox.h:1953
RestConnection conn
The REST connection.
Definition RestClient.qm.dox.h:1920
string state
Current state.
Definition RestClient.qm.dox.h:1947
string path
The URI path to use.
Definition RestClient.qm.dox.h:1938
destructor()
Destroys the object and makes any connection option updates.
string getGoal()
Returns the goal.
const SPS_OAUTH2_GET_TOKEN
OAuth2 get token state.
Definition RestClient.qm.dox.h:1904
hash< auto > real_opts
RestClient options.
Definition RestClient.qm.dox.h:1926
const SPS_GET_SWAGGER
Retrieve Swagger schema.
Definition RestClient.qm.dox.h:1901
RestClient rc
The RestClient object to use for polling I/O.
Definition RestClient.qm.dox.h:1923
const SPS_COMPLETE
Complete state.
Definition RestClient.qm.dox.h:1916
bool use_path_as_is
Use path directly / ping path already prepared.
Definition RestClient.qm.dox.h:1956
*hash< auto > headers
Headers to send.
Definition RestClient.qm.dox.h:1944
const SPS_REST_PING
Execute ping request.
Definition RestClient.qm.dox.h:1913
bool goalReached()
Returns True when the goal as been reached.
AbstractPollOperation poller
The polling object.
Definition RestClient.qm.dox.h:1929
*auto body
The message body to send.
Definition RestClient.qm.dox.h:1941
const SPS_CUSTOM_GET_TOKEN
Custom refresh token state.
Definition RestClient.qm.dox.h:1910
bool goal_reached
Goal reached flag.
Definition RestClient.qm.dox.h:1932
string getState()
Returns the current state.
string method
The HTTP method to use.
Definition RestClient.qm.dox.h:1935
Mutex m()
Lock for atomicity.
constructor(RestConnection conn, RestClient rc, hash< auto > real_opts)
Creates the poller with the REST client and option hash.
the RestClient namespace contains all the objects in the RestClient module
Definition RestClient.qm.dox.h:273
Hash to use for generating authorization code requests.
Definition RestClient.qm.dox.h:277
*string redirect_uri
To override the redirect_uri; if not set, the oauth2_redirect_url option will be used instead.
Definition RestClient.qm.dox.h:282
*list< string > scopes
Scopes to use in the request; if not set, the oauth2_scopes option will be used instead.
Definition RestClient.qm.dox.h:285
string response_type
The response type value to use in the request.
Definition RestClient.qm.dox.h:279
*string state
The state value to use in the request.
Definition RestClient.qm.dox.h:288