All Classes Namespaces Functions Variables Groups Pages
RestClient Module

# 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` and `swagger` options in 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 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 httpclient_get_with_body for more information

# Release Notes

## 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