-
Notifications
You must be signed in to change notification settings - Fork 9
/
RestClient.qm
2720 lines (2399 loc) · 121 KB
/
RestClient.qm
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# -*- mode: qore; indent-tabs-mode: nil -*-
#! @file RestClient.qm Qore user module for calling REST services
/* RestClient.qm Copyright (C) 2013 - 2023 Qore Technologies, s.r.o.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
*/
# minimum qore version
%requires qore >= 1.0
# require type definitions everywhere
%require-types
# enable all warnings
%enable-all-warnings
# don't use "$" for vars, members, and methods, assume local variable scope
%new-style
%enable-all-warnings
%requires Mime >= 1.3
%requires(reexport) ConnectionProvider >= 1.10
%requires(reexport) RestSchemaValidator >= 1.0
%requires Swagger >= 2.0
%requires(reexport) Logger
%try-module yaml >= 0.5
%define NoYaml
%endtry
%try-module xml >= 1.3
%define NoXml
%endtry
%try-module json >= 1.5
%define NoJson
%endtry
module RestClient {
version = "2.1.1";
desc = "user module for calling REST services";
author = "David Nichols <david@qore.org>";
url = "http://qore.org";
license = "MIT";
%ifndef QORE_QDX_RUN
init = sub () {
# if no modules for data de/serialization can be loaded, then throw an exception
if (!RestClient::Accept)
throw "RESTCLIENT-ERROR", sprintf("none of the 'yaml', 'xml', or 'json' modules can be loaded; at least "
"one of which is required to support data de/serialization for REST requests and responses");
ConnectionSchemeCache::registerScheme("rest", RestConnection::ConnectionScheme);
ConnectionSchemeCache::registerScheme("rests", RestConnection::ConnectionScheme);
};
%endif
}
/* Version History - see below in docs
*/
/** @mainpage RestClient Module
@tableofcontents
@section restclientintro RestClient Introduction
The %RestClient module provides an API for calling REST services.
To use this module, use \c "%requires RestClient" in your code.
All the public symbols in the module are defined in the RestClient namespace.
The main classes are:
- @ref RestClient::RestClient "RestClient": this class provides the REST client API
- @ref RestClient::RestConnection "RestConnection": provides a connection object to a REST server (based on the
@ref connectionproviderintro "ConnectionProvider" module)
The @ref RestClient::RestClient "RestClient" class can support the following methods of data serialization:
- \c "json": using the \c "json" module; messages bodies are encoded using JSON
- \c "rawxml": using the \c "xml" module; message bodies are encoded with XML without any data type encodings
- \c "url": message bodies are encoded in URL form encoded format (see
<a href="https://tools.ietf.org/html/rfc1738">RFC 2738 2.2</a>)
- \c "xml": using the \c "xml" module; message bodies are encoded using XML-RPC value encoding
- \c "yaml": using the \c "yaml" module; message bodies are encoded using YAML
- \c "text": message bodies are not serialized, plain text value is used
- \c "bin": message bodies are not serialized, binary data is used instead
If none of the above modules can be loaded by the RestClient module, then the RestClient module will fail to
initialize.
Runtime REST API validation against a REST schema is supported; see the \c validator and \c swagger options in
@ref RestClient::RestClient::constructor() "RestClient::constructor()".
For maximum compatibility with other REST solutions, the \c "json" encoding method is the default when no other
encoding method is chosen and the \c "json" module is available.
@par Example:
@code{.py}
#!/usr/bin/env qore
%requires RestClient
RestClient rest({"url": "http://localhost:8001/rest"});
hash<auto> ans = rest.get("orders/1?option=full");
printf("%N\n", ans.body);
@endcode
@see \c "rest" in the bin directory for a user-friendly command-line interface to REST
functionality and a more detailed example of code using this module.
@note The @ref RestClient::RestClient "RestClient" class allows for HTTP \c GET requests to be made
with a message body, but this is bad practice and not compliant with HTTP 1.1 RFCs and therefore
could lead to compatibility problems; see @ref httpclient_get_with_body for more information
@section restclientrelnotes Release Notes
@subsection restclientv2_1_1 RestClient v2.1.1
- fixed a bug where the OAUth2 refresh token was sometimes dropped when an access token was acquired
(<a href="https://github.com/qorelanguage/qore/issues/4821">issue 4821</a>)
- fixed a bug returning the token URL
(<a href="https://github.com/qorelanguage/qore/issues/4809">issue 4809</a>)
@subsection restclientv2_1 RestClient v2.1
- added @ref RestClient::RestClient::setOAuth2Options() "RestClient::setOAuth2Options()"
- do not try to get another OAuth2 token if the token was just retrieved
(<a href="https://github.com/qorelanguage/qore/issues/4796">issue 4796</a>)
@subsection restclientv2_0 RestClient v2.0
- implemented support for OAuth2 authorization flows
(<a href="https://github.com/qorelanguage/qore/issues/4766">issue 4766</a>)
- fixed handling polling pings of REST connections to respect the connection parameters and behave like the
non-polling ping
(<a href="https://github.com/qorelanguage/qore/issues/4764">issue 4764</a>)
@subsection restclientv1_10_1 RestClient v1.10.1
- fixed URI path reporting in REST error messages
(<a href="https://github.com/qorelanguage/qore/issues/4760">issue 4760</a>)
@subsection restclientv1_10 RestClient v1.10
- implemented the \c swagger_lax_parsing option to try to parse invalid Swagger schemas
(<a href="https://github.com/qorelanguage/qore/issues/4741">issue 4741</a>)
@subsection restclientv1_9_3 RestClient v1.9.3
- allow connection options designating files to be selected as files
(<a href="https://github.com/qorelanguage/qore/issues/4725">issue 4725</a>)
@subsection restclientv1_9_2 RestClient v1.9.2
- support full ping operations, also with polling, using an authenticated request
(<a href="https://github.com/qorelanguage/qore/issues/4677">issue 4677</a>)
- apply the \c swagger_base_path argument to all REST validators
(<a href="https://github.com/qorelanguage/qore/issues/4663">issue 4663</a>)
@subsection restclientv1_9_1 RestClient v1.9.1
- non-blocking polling fixes
(<a href="https://github.com/qorelanguage/qore/issues/4595">issue 4595</a>)
@subsection restclientv1_9 RestClient v1.9
- enable the deserialized body to be returned in REST exception info when possible
(<a href="https://github.com/qorelanguage/qore/issues/4591">issue 4591</a>)
@subsection restclientv1_8 RestClient v1.8
- added support for the DataProvider API
(<a href="https://github.com/qorelanguage/qore/issues/4564">issue 4564</a>)
@subsection restclientv1_7_5 RestClient v1.7.5
- fixed a bug where REST schema validation was not applied in all contexts with specialized REST clients; this
was enabled by refactoring the internal code that allowed the validation to be applied
(<a href="https://github.com/qorelanguage/qore/issues/4518">issue 4518</a>)
@subsection restclientv1_7_4 RestClient v1.7.4
- removed erroneous / extraneous URI encoding on REST paths before sending
(<a href="https://github.com/qorelanguage/qore/issues/4360">issue 4360</a>)
@subsection restclientv1_7_3 RestClient v1.7.3
- additional fixes to REST path handling with schema validators with a base path
(<a href="https://github.com/qorelanguage/qore/issues/4059">issue 4059</a>)
@subsection restclientv1_7_2 RestClient v1.7.2
- better fixes to REST URI path handling with schema validation; ensure that the connection path is always cleared
when a REST validator is present
(<a href="https://github.com/qorelanguage/qore/issues/4059">issue 4059</a>)
@subsection restclientv1_7_1 RestClient v1.7.1
- added the \a swagger_base_path option to REST clients and connections to allow for Swagger schemas to have their
base path overridden
(<a href="https://github.com/qorelanguage/qore/issues/4059">issue 4059</a>)
@subsection restclientv1_7 RestClient v1.7
- implemented support for a data provider scheme cache and rich option information for connections
(<a href="https://github.com/qorelanguage/qore/issues/4025">issue 4025</a>)
- fixed a bug handling complex \c Content-Type headers in responses
(<a href="https://github.com/qorelanguage/qore/issues/4019">issue 4019</a>)
@subsection restclientv1_6_1 RestClient v1.6.1
- added the @ref no_charset option to options
(<a href="https://github.com/qorelanguage/qore/issues/3328">issue 3328</a>)
@subsection restclientv1_6 RestClient v1.6
- fixed a bug where the \c "response-code" key of the info output hash could be missing in some clases
(<a href="https://github.com/qorelanguage/qore/issues/3237">issue 3237</a>)
- all connection clases have unified constructor
@subsection restclientv1_5 RestClient v1.5
- added the @ref RestClient::RestConnection::getConstructorInfo() "RestConnection::getConstructorInfo()"
method to allow connections to be created dynamically, potentially in another process from a network
call (<a href="https://github.com/qorelanguage/qore/issues/2628">issue 2628</a>)
@subsection restclientv1_4_2 RestClient v1.4.2
- fixed a bug handling default options including timeouts in REST connections in
@ref RestClient::RestConnection "RestConnection"
(<a href="https://github.com/qorelanguage/qore/issues/3321">issue 3321</a>)
@subsection restclientv1_4_1 RestClient v1.4.1
- added support for REST requests with binary message bodies; added the \c "bin" serialization method
(<a href="https://github.com/qorelanguage/qore/issues/2816">issue 2816</a>)
@subsection restclientv1_4 RestClient v1.4
- added support for the \c text/plain Content-Type
- added the @ref RestClient::RestConnection "RestConnection" class to support the
<a href="../../ConnectionProvider/html/index.html">ConnectionProvider</a> module
- updated for complex types
- added support for REST API validation with a REST schema through the
@ref restschemavalidatorintro "RestSchemaValidator" module and the @ref swaggerintro "Swagger" module
- added default support for the HTTP \c "PATCH" method
@subsection restclientv1_3_1 RestClient v1.3.1
- added support for the \c "url" encoding for URL form encoded message bodies
(<a href="https://github.com/qorelanguage/qore/issues/1436">issue 1436</a>)
- added support for the \c "rawxml" data type; when parsing XML responses, if the XML cannot be parsed as XML-RPC
data, then it's attempted to be parsed as untyped XML data
(<a href="https://github.com/qorelanguage/qore/issues/1437">issue 1437</a>)
- fixed a bug where an empty chunked response would cause a spurious exception to be thrown
(<a href="https://github.com/qorelanguage/qore/issues/1448">issue 1448</a>)
@subsection restclientv1_3 RestClient v1.3
- added:
- @ref RestClient::RestClient::addDefaultHeaders() "RestClient::addDefaultHeaders()"
- @ref RestClient::RestClient::getDefaultHeaders() "RestClient::getDefaultHeaders()"
- @ref RestClient::RestClient::getSendEncoding() "RestClient::getSendEncoding()"
- @ref RestClient::RestClient::setContentEncoding() "RestClient::setContentEncoding()"
- implemented the \c "content_encoding" option for the RestClient constructor
- made \c "gzip" the default content encoding
- added a compression threshold giving a minimum size for for applying content encoding on message bodies; small
messages will be sent uncompressed
- when possible, REST bodies are decoded and stored in the \a info output argument when the HTTP server returns a
status code < 100 or >= 300 to allow for error-handling in the client
- fixed issues where multiple leading \c "/" chars were sometimes present in the request URI path
- doc updates
@subsection restclientv1_2 RestClient v1.2
- allow the Content-Type header to be overriden in REST requests
- added \a hdr args to REST methods
- fixed a bug using the module when the yaml module is not available
- ensure URI paths are absolute
@subsection restclientv1_1 RestClient v1.1
- updated to use encode_url() before sending HTTP messages
- add charset=xxx to \c "Content-Type" header in requests
- fixed \c "Accept" header in requests
@subsection restclientv1_0 RestClient v1.0
- the initial version of the %RestClient module
*/
#! the RestClient namespace contains all the objects in the RestClient module
public namespace RestClient {
#! Hash to use for generating authorization code requests
/** @since RestClient 2.0
*/
public hashdecl AuthCodeInfo {
#! The response type value to use in the request
string response_type = "code";
#! To override the redirect_uri; if not set, the \c oauth2_redirect_url option will be used instead
*string redirect_uri;
#! Scopes to use in the request; if not set, the \c oauth2_scopes option will be used instead
*list<string> scopes;
#! The state value to use in the request
*string state;
}
#! this class provides the REST client API
public class RestClient inherits Qore::HTTPClient, Logger::LoggerWrapper, ConnectionProvider::UpdateOptionsInterface {
public {
#! Data serialization support mapping codes to MIME types and de/serialization functions
const DataSerializationSupport = {
%ifndef NoJson
"json": MimeTypeJson,
%endif
%ifndef NoYaml
"yaml": MimeTypeYaml,
%endif
%ifndef NoXml
"xml": MimeTypeXml,
"rawxml": MimeTypeXmlApp,
%endif
"url": MimeTypeFormUrlEncoded,
"text": MimeTypeText,
"bin": MimeTypeOctetStream,
};
%ifndef NoYaml
const DeserializeYaml = {
"code": "yaml",
"in": \parse_yaml(),
};
%endif
%ifndef NoXml
const DeserializeXml = {
"code": "xml",
"arg": True,
"in": hash<auto> sub (string xml, reference<string> type) {
try {
on_success type = "xml";
return parse_xmlrpc_value(xml);
} catch (hash<ExceptionInfo> ex) {
try {
on_success type = "rawxml";
return parse_xml(xml);
} catch () {
rethrow;
}
}
},
};
%endif
#! Accept header list
const AcceptList = (
%ifndef NoYaml
MimeTypeYaml, MimeTypeYamlRpc,
%endif
%ifndef NoXml
MimeTypeXml, MimeTypeXmlApp,
%endif
%ifndef NoJson
MimeTypeJsonRpc,
%endif
MimeTypeFormUrlEncoded,
MimeTypeText,
MimeTypeOctetStream,
);
#! Accept header value
const Accept = AcceptList.join(",");
#! Map of acceptable Mime types
const AcceptMap = map {$1: True}, AcceptList;
#! RestClient Version
const Version = "2.0";
#! RestClient Version String
const VersionString = sprintf("Qore-RestClient/%s", RestClient::Version);
#! default HTTP headers (Content-Type is added before sending)
const DefaultHeaders = {
"Accept": Accept,
"User-Agent": RestClient::VersionString,
};
#! Default oauth2_redirect_url option value
const DefaultOAuth2RedirectUrl = "auto";
#! Default option values
const DefaultOptions = {
"oauth2_redirect_url": DefaultOAuth2RedirectUrl,
};
#! Data serialization options; this is a hash to simulate a set of strings
/** Data serialization options are as follows:
- \c "auto": prefers in this order: json, yaml, rawxml, xml, url, and text
- \c "bin": for binary message bodies without data serialization
- \c "json": use only JSON serialization
- \c "rawxml": use raw XML serialization
- \c "text": use only plain text. No serialization is used.
- \c "url": for URL-encoded message bodies
- \c "xml": use only XML-RPC serialization
- \c "yaml": use only YAML serialization
*/
const DataSerializationOptions = {
"auto": True,
%ifndef NoJson
"json": True,
%endif
%ifndef NoYaml
"yaml": True,
%endif
%ifndef NoXml
"rawxml": True,
"xml": True,
%endif
"url": True,
"text": True,
"bin": True,
};
#! Send content encoding options
/** Send content encoding options are as follows:
- \c "bzip": use bzip2 compression
- \c "gzip": use gzip compression
- \c "deflate": use deflate compression
- \c "identity": use no content encoding
*/
const EncodingSupport = {
"gzip": {
"ce": "gzip",
"func": \gzip(),
},
"bzip2": {
"ce": "bzip2",
"func": \bzip2(),
},
"deflate": {
"ce": "deflate",
"func": \compress(),
},
"identity": {
"ce": NOTHING,
},
};
#! default threadhold for data compressions; transfers smaller than this size will not be compressed
const CompressionThreshold = 1024;
#! Option requirements per OAuth2 grant type
/** @note the \c authorization_code grant type cannot be handled automatically
*/
const OAuth2GrantOptions = {
"authorization_code": (
"oauth2_auth_url",
"oauth2_client_id",
"oauth2_client_secret",
"oauth2_redirect_url",
"oauth2_token_url",
),
"client_credentials": (
"oauth2_client_id",
"oauth2_client_secret",
"oauth2_token_url",
),
"password": (
"oauth2_client_id",
"oauth2_client_secret",
"oauth2_token_url",
),
};
#! Headers to send when making an authorization / token request
const OAuth2AuthHeaders = {
# this will ensure that OAuth2 servers do not prefer XML or other serialization with a different data
# format (ex: the Salesforce OAuth2 server)
"Accept": MimeTypeFormUrlEncoded + "," + MimeTypeJson,
};
#! Minimum time between OAuth2 token requests
const MinimumTokenRefresh = 1m;
}
private {
# headers to send with every request
hash<auto> headers;
# data serialization code
string ds;
# serialization content type
string sct;
# send content encoding hash
*hash<auto> seh;
# REST schema validator
RestSchemaValidator::AbstractRestSchemaValidator validator;
# no_charset option
*bool noCharset;
#! username for authentication
string username;
#! password for authentication
string password;
#! OAuth2 grant type
string oauth2_grant_type;
#! OAuth2 client ID
string oauth2_client_id;
#! OAuth2 client secret
string oauth2_client_secret;
#! OAuth2 scope
*softlist<string> oauth2_scopes;
#! OAuth2 extra args
*hash<auto> oauth2_auth_args;
#! OAuth2 auth URL
string oauth2_auth_url;
#! OAuth2 redirect URL
string oauth2_redirect_url;
#! OAuth2 token URL
string oauth2_token_url;
#! The token type, if any
string token_type;
#! Any token set for the connection; will be passed as a bearer token (Authorization: Bearer ...)
string token;
#! Any refresh token granted to the client
string refresh_token;
#! If OAuth2 tokens should be automatically refreshed
bool oauth2_auto_refresh = True;
#! Last timestamp for token acquisition
date token_timestamp;
}
#! calls the base class HTTPClient constructor and optionally connects to the REST server
/** @par Example:
@code{.py}
RestClient rest({"url": "http://localhost:8001/rest"});
@endcode
@param opts valid options are:
- \c additional_methods: Optional hash with more but not-HTTP-standardized methods to handle. It allows to
create various HTTP extensions like e.g. WebDAV. The hash takes the method name as a key, and the value
is a boolean @ref True "True" or @ref False "False": indicating if the method can accept a message body
as well. Example:
@code{.py}
# add new HTTP methods for WebDAV. Both of them require body posting to the server
("additional_methods": ("PROPFIND": True, "MKCOL": True ));
@endcode
- \c connect_timeout: The timeout value in milliseconds for establishing a new socket connection (also can
be a relative date-time value for clarity, ex: \c 20s)
- \c content_encoding: for possible values, see @ref EncodingSupport; this sets the send encoding (if the
\c "send_encoding" option is not set) and the requested response encoding (note that the
@ref RestClient::RestClient "RestClient" class will only compress outgoing message bodies over
@ref RestClient::RestClient::CompressionThreshold "CompressionThreshold" bytes in size)
- \c data: a @ref DataSerializationOptions "data serialization option"; if not present defaults to
\c "auto"
- \c default_path: The default path to use for new connections if a path is not otherwise specified in the
connection URL
- \c default_port: The default port number to connect to if none is given in the URL
- \c error_passthru: if @ref True "True" then HTTP status codes indicating errors will not cause a
\c REST-RESPONSE-ERROR exception to be raised, rather such responses will be passed through to the
caller like any other response
- \c headers: an optional hash of headers to send with every request, these can also be overridden in
request method calls
- \c http_version: Either '1.0' or '1.1' for the claimed HTTP protocol version compliancy in outgoing
message headers
- \c logger: any logger to use for the object
- \c max_redirects: The maximum number of redirects before throwing an exception (the default is 5)
- \c oauth2_auto_refresh: If OAuth2 tokens should be automatically refreshed
(default \c True)
- \c oauth2_auth_args: Extra arguments for OAuth2 authentication requests to \c oauth2_auth_url for the
\c authentication_code grant type. Note that the \c authorization_code grant type requires external user
authorization to acquire an access token
- \c oauth2_auth_url: The OAuth2 authorization URL for the \c authorization_code grant type; ignored if the
\c token option is set. Note that the \c authorization_code grant type requires external user authorization
to acquire an access token
- \c oauth2_client_id: The OAuth2 client ID; ignored if the \c token option is set
- \c oauth2_client_secret: the OAuth2 client secret; ignored if the \c token option is set
- \c oauth2_grant_type: the OAuth2 grant type; ignored if the \c token option is set; possible values:
- \c authorization_code: requires \c oauth2_client_id, \c oauth2_client_secret, \c oauth2_auth_url, as well
as \c 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
- \c client_credentials: requires \c oauth2_client_id, \c oauth2_client_secret, as well as
\c oauth2_token_url
- \c password: requires a username, password, \c oauth2_client_id, \c oauth2_client_secret, as well as
\c oauth2_token_url
- \c oauth2_redirect_url: The OAuth2 redirect URL for the \c authorization_code grant type; ignored if the
\c token option is set. Note that the \c authorization_code grant type requires external user authorization
to acquire an access token; the special value \c "auto" (the default) is meant to be interpreted by servers
that implement OAuth2 authorization code client handling
- \c oauth2_refresh_token: An OAuth2 refresh token (complements option \c token)
- \c oauth2_scopes: A list of OAuth2 scopes to request; ignored if the \c token option is set
- \c oauth2_token_url: The token URL OAuth2 flows; ignored if the \c token option is set
- \c password: The password for authentication; only used if no username or password is set in the URL and if
the \c username option is also used
- \c proxy: The proxy URL for connecting through a proxy
- \c redirect_passthru: if @ref True "True" then redirect responses will be passed to the caller instead
of processed
- \c send_encoding: a @ref EncodingSupport "send data encoding option" or the value \c "auto" which means
to use automatic encoding; if not present defaults to no content-encoding on sent message bodies (note
that the @ref RestClient::RestClient "RestClient" class will only compress outgoing message bodies over
@ref RestClient::RestClient::CompressionThreshold "CompressionThreshold" bytes in size)
- \c swagger: the path to a <a href="https://swagger.io/">Swagger 2.0</a> REST schema file for API
validation; only used if \a validator not provided (see the @ref swaggerintro "Swagger" module)
- \c 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)
- \c timeout: The timeout value in milliseconds (also can be a relative date-time value for clarity, ex:
\c 30s)
- \c token: Any bearer token to use for the connection; will be passed as <tt>Authorization: Bearer ...</tt>
in request headers; conflicts with username and password options or authentication credentials in the URL;
if this option is set then any OAuth2 options are ignored
- \c token_type: The type of token to use for the \c Authentication header; ignored if no \c token option is
set
- \c update_options: Any update token code to use for the object; @see update_options for more information
- \c url: A string giving the URL to connect to; if not given then the target URL will be taken from any
\c validator option, if given by calling
@ref RestSchemaValidator::AbstractRestSchemaValidator::getTargetUrl() "AbstractRestSchemaValidator::getTargetUrl()"
- \c username: The username for authentication; only used if no username or password is set in the URL and
if the \c password option is also used
- \c validator: an @ref RestSchemaValidator::AbstractRestSchemaValidator "AbstractRestSchemaValidator"
object to validate request and response messages; overrides \a swagger
- \c no_charset: if True no charset will be added to the Content-Type header
@param do_not_connect if \c False (the default), then a connection will be immediately established to the
remote server
@throw RESTCLIENT-ERROR invalid option passed to constructor, unsupported data serialization, etc
@since
- %RestClient 1.2 the \a send_encoding option was added
- %RestClient 1.4 the \a validator and \a swagger options were added
*/
constructor(*hash<auto> opts, *softbool do_not_connect)
: HTTPClient(opts + ((opts.url || !opts.validator) ? NOTHING : {"url": opts.validator.getTargetUrl()})) {
# set logger, if any
self.logger = remove opts.logger;
# set update token code, if any
self.update_options = remove opts.update_options;
# apply default option values
opts = DefaultOptions + opts;
setSerialization(opts."data");
if (opts.send_encoding) {
setSendEncoding(opts.send_encoding);
}
if (opts.content_encoding) {
if (!opts.send_encoding) {
setSendEncoding(opts.content_encoding);
} else if (!EncodingSupport.(opts.content_encoding)) {
throw "RESTCLIENT-ERROR", sprintf("content encoding option %y is unknown; valid options: %y",
opts.content_encoding, keys EncodingSupport);
}
opts.headers."Accept-Encoding" = opts.content_encoding;
}
# unconditionally set the encoding to utf-8
setEncoding("utf-8");
# set validator
if (opts.validator) {
if (!(opts.validator instanceof AbstractRestSchemaValidator))
throw "RESTCLIENT-ERROR", sprintf("validator object expected to be an instance of "
"AbstractRestSchemaValidator; got %y instead", opts.validator.fullType());
validator = opts.validator;
if (opts.swagger_base_path) {
validator.setBasePath(opts.swagger_base_path);
}
} else {
if (opts.swagger) {
# this will use FileLocationHandler::getTextFileFileLocation() that reads a file if there is no scheme
validator = SwaggerLoader::fromUrl(opts.swagger, NOTHING,
opts.swagger_lax_parsing ? {"parse_flags": -1} : NOTHING);
if (opts.swagger_base_path) {
validator.setBasePath(opts.swagger_base_path);
}
} else {
validator = new NullRestSchemaValidator();
}
}
if (validator.managesUriPath()) {
# issue #4059: strip the URI path from the URL if it matches the prefix of the REST validator's base path
# otherwise we will run into compatibility problems with the fix
clearConnectionPath();
}
if (exists opts.oauth2_refresh_token) {
refresh_token = opts.oauth2_refresh_token;
}
if (exists opts.oauth2_auto_refresh) {
oauth2_auto_refresh = parse_boolean(opts.oauth2_auto_refresh);
}
if (opts.oauth2_auth_args) {
if (opts.oauth2_auth_args.typeCode() != NT_HASH) {
throw "RESTCLIENT-ERROR", sprintf("option \"oauth2_auth_args\" expects a hash when set; got type %y "
"instead", opts.oauth2_auth_args.fullType());
}
oauth2_auth_args = opts.oauth2_auth_args;
}
if (opts.oauth2_scopes) {
oauth2_scopes = opts.oauth2_scopes;
}
# setup headers before setupAuth()
headers = DefaultHeaders + opts.headers;
noCharset = opts.no_charset;
# setup authentication
setupAuth(opts);
if (!do_not_connect) {
if (oauth2_grant_type && !token) {
loginIntern();
} else {
connect();
}
}
}
#! 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
*/
clearConnectionPath() {
setConnectionPath();
}
#! change the serialization option for the object; see @ref DataSerializationOptions for valid options
/** @par Example:
@code{.py}
rest.setSerialization("yaml");
@endcode
@param data the serialization option for the object; see @ref DataSerializationOptions for valid options
@throw RESTCLIENT-ERROR invalid or unsupported serialization option
@see
- @ref RestClient::RestClient::getSerialization() "RestClient::getSerialization()"
- @ref DataSerializationOptions for valid options
*/
setSerialization(string data = "auto") {
if (!DataSerializationOptions{data})
throw "RESTCLIENT-ERROR", sprintf("data serialization option %y is unknown; valid options: %y", data,
DataSerializationOptions.keys());
if (data == "auto" && DataSerializationSupport) {
delete sct;
} else {
if (!DataSerializationSupport{data})
throw "RESTCLIENT-ERROR", sprintf("data serialization option %y is not supported because the "
"required module could not be loaded; currently supported options: %y", data,
keys DataSerializationSupport);
sct = DataSerializationSupport{data};
}
ds = data;
}
#! change the data content encoding (compression) option for the object
/** @par Example:
@code{.py}
rest.setSendEncoding("gzip");
@endcode
The default is to send requests unencoded/uncompressed.
@param enc the data content encoding (compression) option for the object; see @ref EncodingSupport for valid
options; if the value \c "auto" is passed then \c "gzip" encoding is used
@throw RESTCLIENT-ERROR invalid or unsupported data content encoding / compression option
@see
- @ref RestClient::RestClient::setContentEncoding() "RestClient::setContentEncoding()"
- @ref RestClient::RestClient::getSendEncoding() "RestClient::getSendEncoding()"
- @ref EncodingSupport for valid options
*/
setSendEncoding(string enc = "auto") {
if (enc == "auto") {
seh = EncodingSupport.firstValue();
} else {
if (!EncodingSupport{enc}) {
throw "RESTCLIENT-ERROR", sprintf("send content encoding option %y is unknown; valid options: %y",
enc, keys EncodingSupport);
}
seh = EncodingSupport{enc};
}
}
#! sets the request and desired response encoding for the object; see @ref EncodingSupport for valid options
/** @par Example:
@code{.py}
rest.setContentEncoding("gzip");
@endcode
@param enc the data content encoding (compression) option for requests and the desired response content
encoding for the object; see @ref EncodingSupport for valid options; if the value \c "auto" is passed then
\c "gzip" encoding is used for outgoing requests and requested for responses
@throw RESTCLIENT-ERROR invalid or unsupported data content encoding / compression option
@see
- @ref RestClient::RestClient::getSendEncoding() "RestClient::getSendEncoding()"
- @ref RestClient::RestClient::setSendEncoding() "RestClient::setSendEncoding()"
@since %RestClient 1.3
*/
setContentEncoding(string enc = "auto") {
if (enc == "auto") {
seh = EncodingSupport.firstValue();
} else {
setSendEncoding(enc);
}
headers."Accept-Encoding" = seh.ce ? seh.ce : "identity";
}
#! adds default headers to each request
/** @par Example:
@code{.py}
# disable gzip and bzip encoding in responses
rest.addDefaultHeaders({"Accept-Encoding": "compress"});
@endcode
@param h a hash of headers to add to the default headers to send on each request
@note default headers can also be set in the constructor
Headers added here will be sent in all requests but can be overridden in requests as well.
@see @ref RestClient::RestClient::getDefaultHeaders() "RestClient::getDefaultHeaders()"
@since %RestClient 1.3
*/
addDefaultHeaders(hash<auto> h) {
headers += h;
}
#! returns the hash of default headers to sent in all requests
/** @par Example:
@code{.py}
hash<auto> h = rest.getDefaultHeaders();
@endcode
@return the hash of default headers to sent in all requests
@note default headers can be set in the constructor and in addDefaultHeaders()
@see @ref RestClient::RestClient::addDefaultHeaders() "RestClient::addDefaultHeaders()"
@since %RestClient 1.3
*/
hash<auto> getDefaultHeaders() {
return headers;
}
#! replaces default headers
/** @param hdr The headers to set; @ref DefaultHeaders will be added to this hash to set the default headers for
the object
@since %RestClient 2.0
*/
replaceDefaultHeaders(*hash<auto> hdr) {
headers = DefaultHeaders + hdr;
}
#! returns the current data content encoding (compression) object or @ref nothing if no encoding option is set
/** @par Example:
@code{.py}
*string ce = rest.getSendEncoding();
@endcode
@return the current data content encoding (compression) object or @ref nothing if no encoding option is set;
see @ref EncodingSupport for valid options
@see
- @ref RestClient::RestClient::setContentEncoding() "RestClient::setContentEncoding()"
- @ref RestClient::RestClient::setSendEncoding() "RestClient::setSendEncoding()"
- @ref EncodingSupport for valid options
@since %RestClient 1.3
*/
*string getSendEncoding() {
return seh.ce;
}
#! returns the current data serialization format currently in effect for the object
/** @par Example:
@code{.py}
string ser = rest.getSerialization();
@endcode
@return the current data serialization format currently in effect for the object (see
@ref DataSerializationOptions for possible values)
@see
- @ref RestClient::RestClient::setSerialization() "RestClient::setSerialization()"
- @ref DataSerializationOptions for possible values
*/
string getSerialization() {
return ds;
}
#! sends an HTTP \c GET request to the REST server and returns the response
/** @par Example:
@code{.py}
hash<auto> ans = rest.get("/orders/1?info=verbose");
@endcode
@param path the URI path to add (will be appended to any root path given in the constructor)
@param 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
@ref RestClient::RestClient::constructor() "RestClient::constructor()"; note that sending a message body with
an HTTP \c GET request is not standards compliant; see @ref httpclient_get_with_body for more information; for
maximum compatibility, use @ref nothing for this argument when calling this method
@param 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; if present the hash will contain the following keys:
- \c headers: a hash of outgoing HTTP request headers
- \c request-uri: the request URI string sent (ex: \c "GET /services/async/38.0/job HTTP/1.1")
- \c body-content-type: the outgoing message body Mime \c Content-Type value
- \c response-headers: a hash of processed incoming HTTP headers in the response with keys converted to
lower case and additional information added
- \c response-headers-raw: a hash of raw unprocessed incoming HTTP headers
- \c chunked: set to @ref True "True" if the response was received with chunked transfer encoding
- \c response-code: the HTTP response code
- \c response-body: the raw message body in the response (after any content decoding)
- \c response-serialization: the type of message serialization in the response; see
@ref DataSerializationOptions for possible values when used with the null REST schema validator
- \c request-body: the raw message body in the request (before any content encoding)
- \c request-serialization: the type of message serialization in the request; see
@ref DataSerializationOptions for possible values when used with the null REST schema validator
@param hdr any headers to be sent with the request; headers here will override default headers for the object
as well
@return A hash of headers received from the HTTP server with all key names converted to lower-case; if any
message body is included in the response, it will be deserialized to %Qore data and assigned to the value of
the \c "body" key
@throw DESERIALIZATION-ERROR the response body could not be deserialized (unknown \c Content-Type or invalid
serialization)
@throw REST-RESPONSE-ERROR if this exception is thrown by the @ref 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 \a info hash output keys as follows:
- \c "response-code": the HTTP response code given
- \c "response-headers": a hash of processed response headers
- \c "response-headers-raw": a hash of raw unprocessed response headers
- \c "response-body": the decoded response body
.
Note that this exception is not raised for HTTP status codes indicating an error if the \c error_passthru
option is set to @ref True "True"
Other exceptions can be thrown by the @ref Qore::HTTPClient::send() call used to make the HTTP request.
@see
- @ref RestClient::RestClient::getSerialization() "RestClient::getSerialization()"
- @ref RestClient::RestClient::setSerialization() "RestClient::setSerialization()"
- @ref httpclient_get_with_body
*/
hash<auto> get(string path, auto body, *reference<hash<auto>> info, *hash<auto> hdr) {
return doRequest("GET", path, body, \info, NOTHING, hdr);
}
#! sends an HTTP \c PUT request to the REST server and returns the response
/** @par Example:
@code{.py}
hash<auto> ans = rest.put("/orders/1", ("action": "cancel"));
@endcode
@param path the URI path to add (will be appended to any root path given in the constructor)
@param 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
@ref RestClient::RestClient::constructor() "RestClient::constructor()"
@param 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; if present the hash will contain the following keys:
- \c headers: a hash of outgoing HTTP request headers
- \c request-uri: the request URI string sent (ex: \c "PUT /services/async/38.0/job HTTP/1.1")
- \c body-content-type: the outgoing message body Mime \c Content-Type value
- \c response-headers: a hash of processed incoming HTTP headers in the response with keys converted to
lower case and additional information added
- \c response-headers-raw: a hash of raw unprocessed incoming HTTP headers
- \c chunked: set to @ref True "True" if the response was received with chunked transfer encoding
- \c response-code: the HTTP response code
- \c response-body: the raw message body in the response (after any content decoding)
- \c response-serialization: the type of message serialization in the response; see
@ref DataSerializationOptions for possible values when used with the null REST schema validator
- \c request-body: the raw message body in the request (before any content encoding)
- \c request-serialization: the type of message serialization in the request; see
@ref DataSerializationOptions for possible values when used with the null REST schema validator
@param hdr any headers to be sent with the request; headers here will override default headers for the object
as well
@return A hash of headers received from the HTTP server with all key names converted to lower-case; if any
message body is included in the response, it will be deserialized to %Qore data and assigned to the value of
the \c "body" key
@throw DESERIALIZATION-ERROR the response body could not be deserialized (unknown \c Content-Type or invalid
serialization)
@throw REST-RESPONSE-ERROR if this exception is thrown by the @ref 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 \a info hash output keys as follows:
- \c "response-code": the HTTP response code given
- \c "response-headers": a hash of processed response headers
- \c "response-headers-raw": a hash of raw unprocessed response headers
- \c "response-body": the decoded response body
.
Note that this exception is not raised for HTTP status codes indicating an error if the \c error_passthru
option is set to @ref True "True"