RestClient Module

Table of Contents

• RestClient Introduction
• REST Info Output
• Release Notes
  • RestClient v2.3.3
  • RestClient v2.3.2
  • RestClient v2.3.1
  • RestClient v2.3.0
  • RestClient v2.2.0
  • RestClient v2.1.1
  • RestClient v2.1
  • RestClient v2.0
  • RestClient v1.10.1
  • RestClient v1.10
  • RestClient v1.9.3
  • RestClient v1.9.2
  • RestClient v1.9.1
  • RestClient v1.9
  • RestClient v1.8
  • RestClient v1.7.5
  • RestClient v1.7.4
  • RestClient v1.7.3
  • RestClient v1.7.2
  • RestClient v1.7.1
  • RestClient v1.7
  • RestClient v1.6.1
  • RestClient v1.6
  • RestClient v1.5
  • RestClient v1.4.2
  • RestClient v1.4.1
  • RestClient v1.4
  • RestClient v1.3.1
  • RestClient v1.3
  • RestClient v1.2
  • RestClient v1.1
  • RestClient v1.0

RestClient Introduction

The RestClient module provides an API for calling REST services.

To use this module, use "%requires RestClient" in your code.

All the public symbols in the module are defined in the RestClient namespace.

The main classes are:

• RestClient: this class provides the REST client API
• RestConnection: provides a connection object to a REST server (based on the ConnectionProvider module)

The RestClient class can support the following methods of data serialization:

• "json": using the "json" module; messages bodies are encoded using JSON
• "rawxml": using the "xml" module; message bodies are encoded with XML without any data type encodings
• "url": message bodies are encoded in URL form encoded format (see RFC 2738 2.2)
• "xml": using the "xml" module; message bodies are encoded using XML-RPC value encoding
• "yaml": using the "yaml" module; message bodies are encoded using YAML
• "text": message bodies are not serialized, plain text value is used
• "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 validator, openapi3, and swagger options in RestClient::RestClient::constructor() "RestClient::constructor()".

For maximum compatibility with other REST solutions, the "json" encoding method is the default when no other encoding method is chosen and the "json" module is available.

Example:

//!/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);

See also

"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 RestClient class allows for HTTP 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 HTTP GET Requests With a Message Body for more information

REST Info Output

The info output hash to REST methods has the following format:

• headers: a hash of outgoing HTTP request headers
• request-uri: the request URI string sent (ex: "GET /services/async/38.0/job HTTP/1.1")
• body-content-type: the outgoing message body Mime Content-Type value
• response-headers: a hash of processed incoming HTTP headers in the response with keys converted to lower case and additional information added
• response-headers-raw: a hash of raw unprocessed incoming HTTP headers
• chunked: set to True if the response was received with chunked transfer encoding
• response-body: the message body in the response (after any content decoding and deserialization)
• response-body-raw: the raw message body in the response (after any content decoding)
• response-code: the HTTP response code
• response-serialization: the type of message serialization in the response; see DataSerializationOptions for possible values when used with the null REST schema validator
• request-body: the raw message body in the request (before any content encoding)
• request-serialization: the type of message serialization in the request; see DataSerializationOptions for possible values when used with the null REST schema validator

Release Notes

RestClient v2.3.3

• fixed non-blocking polling with connections that use basic auth (issue 5001)

RestClient v2.3.2

• fixed acqquiring OAuth2 tokens when the oauth2_token_use_basic_auth option is set (issue 4991)
• fixed an infinite loop bug handling token request errors with the client_credentials grant (issue 4990)
• added the allow_any_response option to allow undeserializable responses to be returned as-is
• implemented support for PKCE (issue 4820)
• added a get() method without any body (which shouldn't be sent in GET requests in any case)

RestClient v2.3.1

• fixed passing the correct path to the signature method (issue 4953)

RestClient v2.3.0

• implemented support for custom token operations

RestClient v2.2.0

• major updates and improvements to OAuth2 handling (issue 4820)
• allow the username to be set without a password; assume an empty password

RestClient v2.1.1

• fixed a bug where the OAuth2 refresh token was sometimes dropped when an access token was acquired (issue 4821)
• fixed a bug returning the token URL (issue 4809)

RestClient v2.1

• added RestClient::setOAuth2Options()
• do not try to get another OAuth2 token if the token was just retrieved (issue 4796)

RestClient v2.0

• implemented support for OAuth2 authorization flows (issue 4766)
• fixed handling polling pings of REST connections to respect the connection parameters and behave like the non-polling ping (issue 4764)

RestClient v1.10.1

• fixed URI path reporting in REST error messages (issue 4760)

RestClient v1.10

• implemented the swagger_lax_parsing option to try to parse invalid Swagger schemas (issue 4741)

RestClient v1.9.3

• allow connection options designating files to be selected as files (issue 4725)

RestClient v1.9.2

• support full ping operations, also with polling, using an authenticated request (issue 4677)
• apply the swagger_base_path argument to all REST validators (issue 4663)

RestClient v1.9.1

• non-blocking polling fixes (issue 4595)

RestClient v1.9

• enable the deserialized body to be returned in REST exception info when possible (issue 4591)

RestClient v1.8

• added support for the DataProvider API (issue 4564)

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

RestClient v1.7.4

• removed erroneous / extraneous URI encoding on REST paths before sending (issue 4360)

RestClient v1.7.3

• additional fixes to REST path handling with schema validators with a base path (issue 4059)

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

RestClient v1.7.1

• added the swagger_base_path option to REST clients and connections to allow for Swagger schemas to have their base path overridden (issue 4059)

RestClient v1.7

• implemented support for a data provider scheme cache and rich option information for connections (issue 4025)
• fixed a bug handling complex Content-Type headers in responses (issue 4019)

RestClient v1.6.1

• added the no_charset option to options (issue 3328)

RestClient v1.6

• fixed a bug where the "response-code" key of the info output hash could be missing in some clases (issue 3237)
• all connection clases have unified constructor

RestClient v1.5

• added the RestClient::RestConnection::getConstructorInfo() "RestConnection::getConstructorInfo()" method to allow connections to be created dynamically, potentially in another process from a network call (issue 2628)

RestClient v1.4.2

• fixed a bug handling default options including timeouts in REST connections in RestConnection (issue 3321)

RestClient v1.4.1

• added support for REST requests with binary message bodies; added the "bin" serialization method (issue 2816)

RestClient v1.4

• added support for the text/plain Content-Type
• added the RestConnection class to support the ConnectionProvider module
• updated for complex types
• added support for REST API validation with a REST schema through the RestSchemaValidator module and the Swagger module
• added default support for the HTTP "PATCH" method

RestClient v1.3.1

• added support for the "url" encoding for URL form encoded message bodies (issue 1436)
• added support for the "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 (issue 1437)
• fixed a bug where an empty chunked response would cause a spurious exception to be thrown (issue 1448)

RestClient v1.3

• added:
  • RestClient::addDefaultHeaders()
  • RestClient::getDefaultHeaders()
  • RestClient::getSendEncoding()
  • RestClient::setContentEncoding()
• implemented the "content_encoding" option for the RestClient constructor
• made "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 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 "/" chars were sometimes present in the request URI path
• doc updates

RestClient v1.2

• allow the Content-Type header to be overriden in REST requests
• added hdr args to REST methods
• fixed a bug using the module when the yaml module is not available
• ensure URI paths are absolute

RestClient v1.1

• updated to use encode_url() before sending HTTP messages
• add charset=xxx to "Content-Type" header in requests
• fixed "Accept" header in requests

RestClient v1.0

• the initial version of the RestClient module