QtRestClient

A library for generic JSON-based REST-APIs, with a mechanism to map JSON to Qt objects.

Table of contents

• Features
• Download/Installation
  • Building without QtJsonSerializer/qdep
• Usage
  • Examples
    • API-Definition
    • API-Use
  • Multithreading
    • Simple threading
    • Threadpooling replies
  • API-Generator
    • Example API definition
  • Authentication
    • Example authentication
  • QObject Ownership
• Documentation

<small><i><a href='http://ecotrust-canada.github.io/markdown-toc/'>Table of contents generated with markdown-toc</a></i></small>

Features

• Consume any CBOR or JSON REST-API
• Map API objects to QObject/Q_GADGET classes. Supports:
  • basic objects
  • lists
  • paging objects
  • anything QtJsonSerializer supports
• Allows to create API class representations to wrap specific parts of the api
• Reply-based system - use either signal/slot or a more functional approach
• Custom compiler to generate API objects, classes and methods from simple XML files
• Support for multithreading and threadpools

Download/Installation

There are multiple ways to install the Qt module, sorted by preference:

1. Package Managers: The library is available via:
   • Arch-Linux: AUR-Repository: qt5-restclient
   • MacOs:
     • Tap: brew tap Skycoder42/qt-modules
     • Package: qtrestclient
     • IMPORTANT: Due to limitations of homebrew, you must run source /usr/local/opt/qtrestclient/bashrc.sh before you can use the module. Some goes for the qtjsonserializer dependency
2. Simply add my repository to your Qt MaintenanceTool (Image-based How-To here: Add custom repository):
   1. Start the MaintenanceTool from the commandline using /path/to/MaintenanceTool --addTempRepository <url> with one of the following urls (GUI-Method is currently broken, see QTIFW-1156) - This must be done every time you start the tool:
      • On Linux: https://install.skycoder42.de/qtmodules/linux_x64
      • On Windows: https://install.skycoder42.de/qtmodules/windows_x86
      • On Mac: https://install.skycoder42.de/qtmodules/mac_x64
   2. A new entry appears under all supported Qt Versions (e.g. Qt > Qt 5.11 > Skycoder42 Qt modules)
   3. You can install either all of my modules, or select the one you need: Qt Rest Client
   4. Continue the setup and thats it! you can now use the module for all of your installed Kits for that Qt
3. Download the compiled modules from the release page. Note: You will have to add the correct ones yourself and may need to adjust some paths to fit your installation!
4. Build it yourself! Note: This requires perl to be installed. If you don't have/need cmake, you can ignore the related warnings. To automatically build and install to your Qt installation, run:
   • Install and prepare qdep
   • Install QtJsonSerializer
   • Download the sources. Either use git clone or download from the releases. If you choose the second option, you have to manually create a folder named .git in the projects root directory, otherwise the build will fail.
   • qmake
   • make (If you want the tests/examples/etc. run make all)
   • Optional steps:
     • make doxygen to generate the documentation
     • make -j1 run-tests to build and run all tests
   • make install

Building without QtJsonSerializer/qdep

If you only need the raw JSON-API, without the generic deserialization, then you can build the library without the support for those. To do so, simply run qmake CONFIG+=no_json_serializer instead of a parameterless qmake, and the project will be prepared without those generic APIS (it will also skip creation of qrestbuilder). This also means that the two dependencies, qdep and QtJsonSerializer, are not required anymore and do not have to be installed (you can ignore related warnings).

Also, when building the library in this configuration, do not run make all, as the tests will fail to build against this configuration. Simply run make instead. To build the examples, run make sub-examples.

Important: Please note that you must not include #include <QtRestClient> when using the library in this configuration. Instead, include the needed headers directly, e.g. #include <QtRestClient/RestClient>.

Usage

The restclient is provided as a Qt module. Thus, all you have to do is add the module, and then, in your project, add QT += restclient to your .pro file!

The API consists of 3 main classes:

• RestClient: Set up the API, i.e. how to access it, the base URL and headers
• RestClass: A subset of the API, allows to make requests
• RestReply/GenericRestReply: The reply control returned for every request, to obtain the result and react on errors

Examples

The following examples show an example request made to JSONPlaceholder in different ways.

API-Definition

Before we can start using the API, we have to define c++ objects to map the JSON to. For this example, all we need is to represent a post. This example makes use of Q_GADGET, but it works the same for QObjets as well. MEMBER properties are used for simplicity, it works with any normal property. See QtJsonSerializer for more details about the serialization part. Note: This is optional. You can in fact use the API with JSON only.

struct Post
{
	Q_GADGET

	Q_PROPERTY(int id MEMBER id)
	Q_PROPERTY(int userId MEMBER userId)
	Q_PROPERTY(QString title MEMBER title)
	Q_PROPERTY(QString body MEMBER body)

public:
	Post();

	int id;
	int userId;
	QString title;
	QString body;
};

API-Use

We will now query the data of the post with the id 42. The final URL is: https://jsonplaceholder.typicode.com/posts/42

First, you set up the client, for example in your main:

auto client = new QtRestClient::RestClient();
client->setBaseUrl(QUrl("https://jsonplaceholder.typicode.com"));
QtRestClient::addGlobalApi("jsonplaceholder", client);//optional, makes it easier to use the api

Now, in any class you want to use the api, you can create rest classes to do so:

auto restClass = QtRestClient::createApiClass("jsonplaceholder", "posts", this);//creates a restclass for the registered API, with the sub-path "posts"

Finally, we send the get-request and log the reply:

restClass->get<Post>("42")->onSucceeded([](int statusCode, Post data) {  //calls: GET https://jsonplaceholder.typicode.com/posts/42
	//do whatever you want with the data
	qDebug() << data.id
			 << data.userId
			 << data.title
			 << data.body
});

And thats all you need for a basic API access. Check the documentation for more and important details about the client, the class and the replies!

Multithreading

Generally speaking, the library primarily supports single threaded execution, as all requests and replies are handled asynchronously thanks to signals and slots. For most applications, you should keep it that way, as multithreading will only slow down your application, as long as your workload is not big enough to justify threaded mode.

Please note that it is easily possible to create multiple different instances of the RestClient in their own respective thread. However, if you want to use the same instance in multiple threads, make sure to read the following carefully.

Simple threading

To enable basic threading support, simply set the QtRestClient::RestClient::threaded property to true. This will make all members of the client threadsafe, as well as of any QtRestClient::RestClass belonging to it. From that point on, any request sent via this client will have the requests asynchronously posted to it's original thread. This means requests are still sent from the primary thread, but any steps before that (i.e. creation, serialization, encoding) are run on whatever thread you call the method to send.

The QtRestClient::RestReply classes handle this case transparently, you can use them the same as for normal single threaded operation. The only difference is, that their reply member may be nullptr for a while after sending the request. The handlers assigned to the replies (e.g. onSuccess(...)) will be executed on the same thread as the reply was created on.

For this all to work, all threads that you use any class or reply on, must be a QThread with a running eventloop (QThread::exec). Otherwise the replies will not be notified of the completition and never run any of the handlers.

Threadpooling replies

In addition to this general multithreading support, it is also possible to let QtRestClient::RestReply instances run on a QThreadPool. To do so, you can either call QtRestClient::RestReply::makeAsync or set set QtRestClient::RestClient::asyncPool property - the latter affecting all replies crea