RestClient.qm

# -*- mode: qore; indent-tabs-mode: nil -*-
#! @file RestClient.qm Qore user module for calling REST services

/*  RestClient.qm Copyright (C) 2013 - 2022 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.4
%requires(reexport) RestSchemaValidator >= 1.0
%requires Swagger >= 2.0

%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 = "1.9.2";
    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 restclientv1_9_2 RestClient v1.9.2
    - 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 {
#! this class provides the REST client API
public class RestClient inherits Qore::HTTPClient {
    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 = "1.7";

        #! 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,
        };

        #! 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;
    }

    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;
    }

    #! 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 max_redirects: The maximum number of redirects before throwing an exception (the default is 5)
        - \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 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 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()})) {
        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, EncodingSupport.keys());
            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.type());
            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);
                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 (!do_not_connect)
            connect();

        headers = DefaultHeaders + opts.headers;
        noCharset = opts.no_charset;
    }

    #! 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()"
    */
    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; see @ref EncodingSupport for valid options
    /** @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()"
    */
    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, EncodingSupport.keys());
            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; these headers will be sent in all requests but can be overridden in requests as well
    /** @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

        @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;
    }

    #! returns the current data content encoding (compression) object or @ref nothing if no encoding option is set; see @ref EncodingSupport for valid options
    /** @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()"

        @since %RestClient 1.3
    */
    *string getSendEncoding() {
        return seh.ce;
    }

    #! returns the current data serialization format currently in effect for the object (see @ref DataSerializationOptions for possible values)
    /** @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()"
    */
    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"

        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()"
    */
    hash<auto> put(string path, auto body, *reference<hash<auto>> info, *hash<auto> hdr) {
        return doRequest("PUT", path, body, \info, NOTHING, hdr);
    }

    #! sends an HTTP \c PATCH request to the REST server and returns the response
    /** @par Example:
        @code{.py}
hash<auto> ans = rest.patch("/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 "PATCH /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()"
    */
    hash<auto> patch(string path, auto body, *reference<hash<auto>> info, *hash<auto> hdr) {
        return doRequest("PATCH", path, body, \info, NOTHING, hdr);
    }

    #! sends an HTTP \c POST request to the REST server and returns the response
    /** @par Example:
        @code{.py}
hash<auto> ans = rest.post("/orders", ("product": "xyz123", "options": 500));
        @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 "POST /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()"
    */
    hash<auto> post(string path, auto body, *reference<hash<auto>> info, *hash<auto> hdr) {
        return doRequest("POST", path, body, \info, NOTHING, hdr);
    }

    #! sends an HTTP \c DELETE request to the REST server and returns the response
    /** @par Example:
        @code{.py}
hash<auto> ans = rest.del("/orders/1");
        @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 "DELETE /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()"
    */
    hash<auto> del(string path, auto body, *reference<hash<auto>> info, *hash<auto> hdr) {
        return doRequest("DELETE", path, body, \info, NOTHING, hdr);
    }

    #! returns the current validator object
    /** @return the current validator object

        @since %RestClient 1.4
    */
    RestSchemaValidator::AbstractRestSchemaValidator getValidator() {
        return validator;
    }

    #! sets up the Content-Type header and encodes any body for sending
    private nothing prepareMsg(string method, string path, reference<auto> body, reference<hash<auto>> hdr,
            string ct = "Content-Type") {
        # use {} + ... here to ensure that hdr stays "hash<auto>"
        hdr = {} + headers + hdr;

        # must get the path from the HTTPClient object if not given in the request
        if (!path.val() && (*string p = getConnectionPath()))
            path = p;

        hash<RestRequestClientInfo> req = validator.processRequest(method, path, body, hdr, sct);

        if (exists body) {
            body = req.body;
            if (!hdr{ct})
                hdr{ct} = req.content;
            if (!noCharset && body.typeCode() == NT_STRING && hdr{ct} !~ /;charset=/)
                hdr{ct} += ";charset=" + body.encoding();
            if (seh.ce && body.size() > CompressionThreshold) {
                hdr."Content-Encoding" = seh.ce;
                body = seh.func(body);
            }
        }
    }

    #! sets up the path for the HTTP request URI
    private nothing preparePath(reference<string> path) {
        # strip leading "/" off the given path
        path =~ s/^\/+//;

        # prepare path = connection path + base path + path
        *string p = getConnectionPath();
        string base_path = validator.getBasePath();
        if (base_path.val() && base_path != "/" && path.comparePartial(base_path[1..])) {
            # strip trailing "/" off the base path
            base_path =~ s/\/+$//;
            path = base_path + (path.val() ? ("/" + path) : "");
        }

        if (p.val() && p != "/") {
            # strip trailing "/" off the connection path
            p =~ s/\/+$//;
            path = p + (path.val() ? ("/" + path) : "");
        }

        # ensure path is absolute
        if (path !~ /^\//) {
            splice path, 0, 0, "/";
        }

        # NOTE: Qore will perform URL encoding on the URL + path
    }

    #! sends an HTTP request to the REST server and returns the response
    /** @par Example:
        @code{.py}
hash<auto> ans = rest.doRequest("DELETE", "/orders/1");
        @endcode

        @param m the HTTP method to be used; case is ignored (if not a valid method an \c HTTP-CLIENT-METHOD-ERROR
        exception is raised)
        @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 "POST /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 decode_errors decode the message body with HTTP error responses and throw an exception based on the
        message body
        @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 HTTP-CLIENT-METHOD-ERROR invalid HTTP method argument passed
        @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"
        @throw 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 @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> doRequest(string m, string path, auto body, *reference<hash<auto>> info, softbool decode_errors = True,
            *hash<auto> hdr) {
        prepareMsg(m, path, \body, \hdr);

        on_exit if (exists body) {
            info += {
                "request-body": body,
                "request-serialization": ds,
            };
        }

        # prepare path
        preparePath(\path);

        on_error rethrow $1.err, sprintf("%s (REST URL %y)", $1.desc, getSafeURL());

        return sendAndDecodeResponse(body, m, path, hdr, \info, decode_errors);
    }

    #! The same as doRequest() except no schema validation is performed on the request
    /** @since RestClient 1.7.2
    */
    hash<auto> doValidatedRequest(string m, string path, auto body, *reference<hash<auto>> info,
            softbool decode_errors = True, *hash<auto> hdr) {
        # use {} + ... here to ensure that hdr stays "hash<auto>"
        hdr = {} + headers + hdr;

        on_exit if (exists body) {
            info += {
                "request-body": body,
                "request-serialization": ds,
            };
        }

        return sendAndDecodeResponse(body, m, path, hdr, \info, decode_errors);
    }

    #! sends the outgoing HTTP message and recodes the response to data
    private hash<auto> sendAndDecodeResponse(*data body, string m, string path, hash<auto> hdr,
            *reference<hash<auto>> info, *softbool decode_errors) {
        hash<auto> h;
        try {
            h = send(body, m, path, hdr, False, \info);
            info."response-code" = h.status_code;
        } catch (hash<ExceptionInfo> ex) {
            info."response-code" = info."response-headers".status_code;
            if (ex.arg) {
                if (decode_errors && ex.arg.body) {
                    decodeError(ex.arg, \info);
                    ex.arg.deserialized_body = info."response-body";
                }
            }

            rethrow ex.err, ex.desc, ex.arg;
        }

        on_error {
            if (exists h.body && !exists info."response-body") {
                info."response-body" = h.body;
            }
        }

        return processRestResponse(h, m, path, \info);
    }

    #! Process the raw REST response received
    /** @param resp the return value from HTTPClient::send()
        @param method the HTTP method used
        @param path the URI path used
        @param info an optional info hash reference for information about the call

        @return \a resp with additional or processed information
    */
    private hash<auto> processRestResponse(hash<auto> resp, string method, string path, *reference<hash<auto>> info) {
        hash<RestResponseClientInfo> sh = validator.parseResponse(method, path, resp.status_code, resp.body, resp);
        if (exists resp.body) {
            resp.body = sh.body;
            info += {
                "response-serialization": sh.info."code"
                    ?? NullRestSchemaValidator::DataDeserializationSupport{resp."content-type"}."code"
                    ?? "unknown",
                "response-body": resp.body,
            };
        }

        return resp;
    }

    #! decode any REST errors returned if possible
    static private decodeError(hash<auto> h, *reference<hash<auto>> info) {
        try {
            RestClient::tryDecodeErrorResponse(\h, \info);
            info."response-body" = h.body;
        } catch (hash<ExceptionInfo> ex) {
            # ignore decoding exceptions
        }
        if (h.body.err) {
            if (h.body.desc.typeCode() == NT_STRING)
                trim h.body.desc;
            throw h.body.err, h.body.desc, h.body.arg;
        }
        if (h.body && h.body.typeCode() == NT_STRING) {
            trim h.body;
            throw "REST-RESPONSE-ERROR", h.body;
        }
    }

    #! tries to decode an error response
    static private:internal tryDecodeErrorResponse(reference<hash<auto>> h, *reference<hash<auto>> info) {
        #info."response-body" = h.body;
        string ct = (h."content-type".typeCode() == NT_LIST
            ? h."content-type"[0]
            : h."content-type");
        *hash<auto> dh = NullRestSchemaValidator::DataDeserializationSupport{ct};
        if (!dh) {
            throw "DESERIALIZATION-ERROR", sprintf("cannot deserialize response body; content-type is: %y; types "
                "supported: %y; response body: %y", h."content-type",
                NullRestSchemaValidator::DataDeserializationSupport.keys(), h.body);
        }

        string code = dh."code";
        h.body = dh.arg
            ? dh.in(h.body, \code)
            : dh.in(h.body);

        info."response-serialization" = code;
    }

} # class RestClient

#! class for REST HTTP connections; returns @ref RestClient::RestClient objects
/** supports the following options:
    - \c "connect_timeout": connection timeout to use in milliseconds
    - \c "content_encoding": this sets the send encoding (if the \c "send_encoding" option is not set) and the
        requested response encoding; for possible values, see
        @ref RestClient::RestClient::EncodingSupport "EncodingSupport"
    - \c "data": see @ref RestClient::RestClient::DataSerializationOptions for possible values when used with the
        null REST schema validator; the default is \c "auto"
    - \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; also a string giving headers can be given in the format:
        <tt>header1=value, header2=value</tt>; the value will be parsed with
        @ref Util::parse_to_qore_value() "parse_to_qore_value()"
    - \c "http_version": HTTP version to use (\c "1.0" or \c "1.1", defaults to \c "1.1")
    - \c "max_redirects": maximum redirects to support
    - \c "proxy": proxy URL to use
    - \c "redirect_passthru": if @ref True "True" then redirect responses will be passed to the caller instead of
        processed
    - \c "send_encoding": a @ref RestClient::RestClient::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
    - \c "swagger": the path to a <a href="https://swagger.io/">Swagger 2.0</a> REST schema file for runtime API
        validation (see the @ref swaggerintro "Swagger" module); conflicts with \a validator
    - \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": transfer timeout to use in milliseconds
    - \c "validator": an @ref RestSchemaValidator::AbstractRestSchemaValidator "AbstractRestSchemaValidator"
        object to validate request and response messages; conflicts with \a swagger

    @note additionally supports the following runtime option in getImpl():
    - \c "validator": an @ref RestSchemaValidator::AbstractRestSchemaValidator "AbstractRestSchemaValidator"
        object for REST message validation (if present, overrides any REST schema validation option provided as a
        connection option)

    @see @ref RestClient::RestClient::constructor() "RestClient::constructor()" for more information on the above
    options

    @since %RestConnection 1.4
*/
public class RestConnection inherits ConnectionProvider::HttpBasedConnection {
    public {
        #! real options used when creating an object
        hash<auto> real_opts;

        #! Connection entry info
        const ConnectionScheme = <ConnectionSchemeInfo>{
            "cls": Class::forName("RestConnection"),
            "options": HttpConnection::ConnectionScheme.options + {
                "content_encoding": <ConnectionOptionInfo>{
                    "type": "string",
                    "desc": "this sets the send encoding (if the `send_encoding` option is not set) and the "
                        "response encoding to request",
                    "allowed_values": (
                        <AllowedValueInfo>{
                            "value": "gzip",
                            "desc": "use GNU zip encoding ([RFC 1952](https://tools.ietf.org/html/rfc1952))",
                        }, <AllowedValueInfo>{
                            "value": "bzip2",
                            "desc": "use bzip2 encoding",
                        }, <AllowedValueInfo>{
                            "value": "deflate",
                            "desc": "use the deflate algorithm ([RFC 1951](https://tools.ietf.org/html/rfc1951))",
                        }, <AllowedValueInfo>{
                            "value": "identity",
                            "desc": "use no content encoding",
                        },
                    ),
                },
                "data": <ConnectionOptionInfo>{
                    "type": "string",
                    "desc": "data serialization options",
                    "allowed_values": (
                        <AllowedValueInfo>{
                            "value": "auto",
                            "desc": "prefers in this order: `json`, `yaml`, `rawxml`, `xml`, `url`, and `text`",
                        }, <AllowedValueInfo>{
                            "value": "bin",
                            "desc": "for binary message bodies without data serialization",
                        }, <AllowedValueInfo>{
                            "value": "json",
                            "desc": "use JSON serialization",
                        }, <AllowedValueInfo>{
                            "value": "rawxml",
                            "desc": "use raw XML serialization",
                        }, <AllowedValueInfo>{
                            "value": "text",
                            "desc": "use only plain text; no serialization is used",
                        }, <AllowedValueInfo>{
                            "value": "url",
                            "desc": "for URL-encoded message bodies",
                        }, <AllowedValueInfo>{
                            "value": "xml",
                            "desc": "use only XML-RPC serialization",
                        }, <AllowedValueInfo>{
                            "value": "yaml",
                            "desc": "use only YAML serialization",
                        },
                    ),
                    "default_value": "auto",
                },
                "headers": <ConnectionOptionInfo>{
                    "type": "hash",
                    "desc": "an optional hash of headers to send with every request, these can also be "
                        "overridden in request method calls",
                },
                "send_encoding": <ConnectionOptionInfo>{
                    "type": "string",
                    "desc": "this sets the send encoding",
                    "allowed_values": (
                        <AllowedValueInfo>{
                            "value": "gzip",
                            "desc": "use GNU zip encoding ([RFC 1952](https://tools.ietf.org/html/rfc1952))",
                        }, <AllowedValueInfo>{
                            "value": "bzip2",
                            "desc": "use bzip2 encoding",
                        }, <AllowedValueInfo>{
                            "value": "deflate",
                            "desc": "use the deflate algorithm ([RFC 1951](https://tools.ietf.org/html/rfc1951))",
                        }, <AllowedValueInfo>{
                            "value": "identity",
                            "desc": "use no content encoding",
                        },
                    ),
                },
                "swagger": <ConnectionOptionInfo>{
                    "type": "string",
                    "desc": "the location of a Swagger schema to use for message validation; processed with "
                        "`FileLocationHandler::getTextFileFromLocation()` "
                        "(ex: `file:///path/to/swagger-schema.json`); conflicts with `validator`",
                },
                "swagger_base_path": <ConnectionOptionInfo>{
                    "type": "string",
                    "desc": "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)",
                    "subst_env_vars": True,
                },
                "validator": <ConnectionOptionInfo>{
                    "type": "any",
                    "desc": "an `AbstractRestSchemaValidator` object for REST message validation; conflicts with "
                        "`swagger`",
                },
            },
        };

        #! object connection options
        const Options = map {$1: True}, keys ConnectionScheme.options;

        #! default options
        const DefaultOptions = map {$1.key: $1.value.default_value}, ConnectionScheme.options.pairIterator(),
            exists $1.value.default_value;

        #! object connection option list
        const OptionList = keys ConnectionScheme.options;
    }

    #! creates the RestConnection connection object
    /** @param name the name of the connection
        @param description connection description
        @param url connection URL (potentially with password info)
        @param attributes various attributes. See below
        @param options connection options

        See @ref AbstractConnection::constructor() for \c attributes and \c options reference.

        @par Additional Attributes
        - \c error a custom error string

        @throw CONNECTION-OPTION-ERROR missing or invalid connection option
    */
    constructor(string name, string description, string url, hash<auto> attributes = {}, hash<auto> options = {})
            : HttpBasedConnection(name, description, url, attributes, RestConnection::processOptions(options)) {
        real_opts = {"url": real_url} + opts;
        children_can_support_apis = True;
        children_can_support_records = exists opts.validator || exists opts.swagger;
    }

    #! returns a @ref RestClient::RestClient "RestClient" object
    /** @param connect if @ref True "True", then the connection is returned already connected
        @param rtopts supports the following runtime option in getImpl():
        - \c "validator": an @ref RestSchemaValidator::AbstractRestSchemaValidator "AbstractRestSchemaValidator"
          object for REST message validation (if present, overrides any REST schema validation option provided as a
          connection option)

        @return a @ref RestClient::RestClient "RestClient" object
    */
    private RestClient getImpl(bool connect = True, *hash<auto> rtopts) {
        return new RestClient(real_opts + (rtopts.validator ? {"validator": rtopts.validator} : NOTHING), !connect);
    }

    #! Returns an unconnected object for a non-blocking poll operation
    /** @return an unconnected object for a non-blocking poll operation

        @since %RestClient 1.9.1
    */
    object getPollImpl() {
        # ensure that no validator is used, as loading the schema cannot be done in a nonblocking way in the polling
        # thread
        return getImpl(False, {"validator": new NullRestSchemaValidator()});
    }

    #! gets options
    /** @return returns a hash with the following supported options:
        - \c "connect_timeout": connection timeout to use in milliseconds
        - \c "content_encoding": this sets the send encoding (if the \c "send_encoding" option is not set) and the
            requested response encoding; for possible values, see
            @ref RestClient::RestClient::EncodingSupport "EncodingSupport"
        - \c "data": see @ref RestClient::RestClient::DataSerializationOptions for possible values when used with the
            null REST schema validator; the default is \c "auto"
        - \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; also a string giving headers can be given in the format:
            <tt>header1=value, header2=value</tt>; the value will be parsed with
            @ref Util::parse_to_qore_value() "parse_to_qore_value()"
        - \c "http_version": HTTP version to use (\c "1.0" or \c "1.1", defaults to \c "1.1")
        - \c "max_redirects": maximum redirects to support
        - \c "proxy": proxy URL to use
        - \c "redirect_passthru": if @ref True "True" then redirect responses will be passed to the caller instead of
            processed
        - \c "send_encoding": a @ref RestClient::RestClient::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
        - \c "swagger": the path to a <a href="https://swagger.io/">Swagger 2.0</a> REST schema file for runtime API
            validation (see the @ref swaggerintro "Swagger" module); conflicts with \a validator
        - \c "timeout": transfer timeout to use in milliseconds
        - \c "validator": an @ref RestSchemaValidator::AbstractRestSchemaValidator "AbstractRestSchemaValidator"
            object to validate request and response messages; conflicts with \a swagger

        @see @ref RestClient::RestClient::constructor() "RestClient::constructor()" for more information on the above
        options
    */
    hash<auto> getOptions() {
        return Options;
    }

    #! returns default options
    *hash<auto> getDefaultOptions() {
        return DefaultOptions;
    }

    #! returns \c "rest"
    string getType() {
        return "rest";
    }

    #! returns a data provider object for this connection
    /** @return a data provider object for this connection; the data provider is:
        - \c SwaggerDataProvider: if an appropriate schema is configured
        - \c RestClientDataProvider: if there is no schema configured

        @throw DATA-PROVIDER-ERROR this object does not support the data provider API
    */
    DataProvider::AbstractDataProvider getDataProvider() {
        if (opts.validator || opts.swagger) {
            # get a REST client object without connecting
            RestClient rest = get(False);
            # get any validator
            *AbstractRestSchemaValidator validator = rest.getValidator();
            if (validator) {
                # if there's a validator, return the provider
                return validator.getDataProvider(rest);
            }
        }

        # to avoid circular dependencies, this object loads the RestClientDataProvider and creates the data provider
        # object dynamically
        load_module("RestClientDataProvider");
        return create_object("RestClientDataProvider", get());
    }

    #! returns @ref True, as this connection always returns a data provider with the @ref getDataProvider() method
    /** @return @ref True, as this connection always returns a data provider with the @ref getDataProvider() method

        @see @ref getDataProvider()
    */
    bool hasDataProvider() {
        return True;
    }

    #! processes options for the constructor
    /** In particular it parses any string as a value of the \c "headers" option to return a hash
    */
    static hash<auto> processOptions(*hash<auto> opts) {
        hash<auto> rv = {} + opts;
        switch (opts.headers.typeCode()) {
            case NT_NOTHING:
            case NT_HASH:
                break;
            case NT_STRING: {
                auto v = parse_to_qore_value(opts.headers);
                if (v.typeCode() != NT_HASH) {
                    throw "REST-CONNECTION-ERROR", sprintf("\"headers\" option string parsed to type %y "
                        "(value: %y); expecting \"hash\"",
                        v.type(), v);
                }
                v = map {$1.key: $1.value.toString()}, v.pairIterator();
                rv.headers = v;
                break;
            }
            default:
                throw "REST-CONNECTION-ERROR", sprintf("\"headers\" option is type %y; expecting \"hash\"",
                    opts.headers.type());
        }
        # prefer "validator" over "swagger"
        if (opts.swagger && opts.validator) {
            throw "REST-CONNECTION-ERROR", "cannot include both \"validator\" and \"swagger\" options";
        }
        if (opts.validator && !(opts.validator instanceof AbstractRestSchemaValidator)) {
            throw "REST-CONNECTION-ERROR", sprintf("\"validator\" is type %y; expecting an "
                "AbstractRestSchemaValidator object", opts.validator.fullType());
        }
        return rv;
    }

    #! Sets child data provider capabilities
    private setChildCapabilities() {
        children_can_support_apis = True;
    }

    #! Returns the ConnectionSchemeInfo hash for this object
    private hash<ConnectionSchemeInfo> getConnectionSchemeInfoImpl() {
        return ConnectionScheme;
    }
}
}