A class to define access to an API, with general settings. More...

#include <restclient.h>

Inheritance diagram for QtRestClient::RestClient:

Public Types
enum	DataMode { DataMode::Cbor, DataMode::Json }
	The different data modes in which the client can operate. More...

Public Slots
void	setManager (QNetworkAccessManager *manager)
	Sets the network access manager to be used by all requests for this client. More...

void	setSerializer (QtJsonSerializer::SerializerBase *serializer)
	Sets the json serializer to be used by all requests for this client. More...

void	setPagingFactory (IPagingFactory *factory)
	Sets the paging factory to be used by all paging requests for this client. More...

void	setDataMode (DataMode dataMode)
	WRITE accessor for RestClient::dataMode.

void	setBaseUrl (QUrl baseUrl)
	WRITE accessor for RestClient::baseUrl.

void	setApiVersion (QVersionNumber apiVersion)
	WRITE accessor for RestClient::apiVersion.

void	setGlobalHeaders (HeaderHash globalHeaders)
	WRITE accessor for RestClient::globalHeaders.

void	setGlobalParameters (QUrlQuery globalParameters)
	WRITE accessor for RestClient::globalParameters.

void	setRequestAttributes (QHash< QNetworkRequest::Attribute, QVariant > requestAttributes)
	WRITE accessor for RestClient::requestAttributes.

void	setModernAttributes ()
	Sets modern attributes in RestClient::requestAttributes. More...

void	setThreaded (bool threaded)
	WRITE accessor for RestClient::threaded.

void	setSslConfiguration (QSslConfiguration sslConfiguration)
	WRITE accessor for RestClient::sslConfiguration.

void	setAsyncPool (QThreadPool *asyncPool)
	WRITE accessor for RestClient::asyncPool.

void	addGlobalHeader (const QByteArray &name, const QByteArray &value)
	WRITE accessor for RestClient::globalHeaders.

void	removeGlobalHeader (const QByteArray &name)
	WRITE accessor for RestClient::globalHeaders.

void	addGlobalParameter (const QString &name, const QString &value)
	WRITE accessor for RestClient::globalParameters.

void	removeGlobalParameter (const QString &name)
	WRITE accessor for RestClient::globalParameters.

void	addRequestAttribute (QNetworkRequest::Attribute attribute, const QVariant &value)
	WRITE accessor for RestClient::requestAttributes.

void	removeRequestAttribute (QNetworkRequest::Attribute attribute)
	WRITE accessor for RestClient::requestAttributes.

Signals
void	dataModeChanged (DataMode dataMode, QPrivateSignal)
	NOTIFY accessor for RestClient::dataMode.

void	baseUrlChanged (QUrl baseUrl, QPrivateSignal)
	NOTIFY accessor for RestClient::baseUrl.

void	apiVersionChanged (QVersionNumber apiVersion, QPrivateSignal)
	NOTIFY accessor for RestClient::apiVersion.

void	globalHeadersChanged (HeaderHash globalHeaders, QPrivateSignal)
	NOTIFY accessor for RestClient::globalHeaders.

void	globalParametersChanged (QUrlQuery globalParameters, QPrivateSignal)
	NOTIFY accessor for RestClient::globalParameters.

void	requestAttributesChanged (QHash< QNetworkRequest::Attribute, QVariant > requestAttributes, QPrivateSignal)
	NOTIFY accessor for RestClient::requestAttributes.

void	threadedChanged (bool threaded, QPrivateSignal)
	NOTIFY accessor for RestClient::threaded.

void	sslConfigurationChanged (QSslConfiguration sslConfiguration, QPrivateSignal)
	NOTIFY accessor for RestClient::sslConfiguration.

void	asyncPoolChanged (QThreadPool *asyncPool, QPrivateSignal)
	NOTIFY accessor for RestClient::asyncPool.

Public Member Functions
	RestClient (QObject *parent=nullptr)
	Constructor.

	RestClient (DataMode dataMode, QObject *parent=nullptr)
	Constructor with a data mode.

	RestClient (QtJsonSerializer::SerializerBase serializer, QObject parent=nullptr)
	Constructor with a serializer.

RestClass *	createClass (const QString &path, QObject *parent=nullptr)
	Creates a new rest class for the given path and parent. More...

RestClass *	rootClass () const
	Returns the rest class with the root path. More...

QNetworkAccessManager *	manager () const
	Returns the network access manager used by the restclient. More...

QtJsonSerializer::SerializerBase *	serializer () const
	Returns the json serializer used by the restclient. More...

IPagingFactory *	pagingFactory () const
	Returns the paging factory used by the restclient. More...

DataMode	dataMode () const
	READ accessor for RestClient::dataMode.

QUrl	baseUrl () const
	READ accessor for RestClient::baseUrl.

QVersionNumber	apiVersion () const
	READ accessor for RestClient::apiVersion.

HeaderHash	globalHeaders () const
	READ accessor for RestClient::globalHeaders.

QUrlQuery	globalParameters () const
	READ accessor for RestClient::globalParameters.

QHash< QNetworkRequest::Attribute, QVariant >	requestAttributes () const
	READ accessor for RestClient::requestAttributes.

bool	isThreaded () const
	READ accessor for RestClient::threaded.

QSslConfiguration	sslConfiguration () const
	READ accessor for RestClient::sslConfiguration.

QThreadPool *	asyncPool () const
	READ accessor for RestClient::asyncPool.

virtual RequestBuilder	builder () const
	Creates a request builder with all the settings of this client. More...

Public Member Functions inherited from QObject
virtual const QMetaObject *	metaObject () const const

	QObject (QObject *parent)

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

QString	objectName () const const

void	setObjectName (const QString &name)

bool	isWidgetType () const const

bool	isWindowType () const const

bool	signalsBlocked () const const

bool	blockSignals (bool block)

QThread *	thread () const const

void	moveToThread (QThread *targetThread)

int	startTimer (int interval, Qt::TimerType timerType)

int	startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)

void	killTimer (int id)

T	findChild (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const

const QObjectList &	children () const const

void	setParent (QObject *parent)

void	installEventFilter (QObject *filterObj)

void	removeEventFilter (QObject *obj)

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const const

bool	disconnect (const char signal, const QObject receiver, const char *method) const const

bool	disconnect (const QObject receiver, const char method) const const

void	dumpObjectTree ()

void	dumpObjectInfo ()

void	dumpObjectTree () const const

void	dumpObjectInfo () const const

bool	setProperty (const char *name, const QVariant &value)

QVariant	property (const char *name) const const

QList< QByteArray >	dynamicPropertyNames () const const

void	destroyed (QObject *obj)

void	objectNameChanged (const QString &objectName)

QObject *	parent () const const

bool	inherits (const char *className) const const

void	deleteLater ()

	Q_DISABLE_COPY (Class)

	Q_DISABLE_MOVE (Class)

	Q_DISABLE_COPY_MOVE (Class)

T	qobject_cast (QObject *object)

T	qobject_cast (const QObject *object)

T	qFindChild (const QObject *obj, const QString &name)

QList< T >	qFindChildren (const QObject *obj, const QString &name)

QList< T >	qFindChildren (const QObject *obj, const QRegExp &regExp)

	Q_CLASSINFO (Name, Value)

	Q_INTERFACES (...)

	Q_PROPERTY (...)

	Q_ENUMS (...)

	Q_FLAGS (...)

	Q_ENUM (...)

	Q_FLAG (...)

	Q_ENUM_NS (...)

	Q_FLAG_NS (...)

	Q_OBJECT Q_OBJECT

	Q_GADGET Q_GADGET

	Q_NAMESPACE Q_NAMESPACE

	Q_SIGNALS Q_SIGNALS

	Q_SIGNAL Q_SIGNAL

	Q_SLOTS Q_SLOTS

	Q_SLOT Q_SLOT

	Q_EMIT Q_EMIT

	Q_INVOKABLE Q_INVOKABLE

	Q_REVISION Q_REVISION

	Q_SET_OBJECT_NAME (Object)

	QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT

Properties
DataMode	dataMode
	The data mode the client is currently in. More...

QUrl	baseUrl
	The base URL to be used for every request to that api. More...

QVersionNumber	apiVersion
	The version number to be appended to the path. More...

HeaderHash	globalHeaders
	A collection of headers to be added to every request. More...

QUrlQuery	globalParameters
	A URL Query with parameters to be added to every request. More...

QHash< QNetworkRequest::Attribute, QVariant >	requestAttributes
	A collection of attributes to be set on every request. More...

bool	threaded
	Specifies, whether the client can be used in a multithreaded context. More...

QSslConfiguration	sslConfiguration
	The SSL configuration to be used for HTTPS. More...

QThreadPool	asyncPool
	Holds a thread pool to be used by all replies created via this clients classes. More...

Properties inherited from QObject
	objectName

Additional Inherited Members
Static Public Member Functions inherited from QObject
QString	tr (const char sourceText, const char disambiguation, int n)

QString	trUtf8 (const char sourceText, const char disambiguation, int n)

QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject context, Functor functor, Qt::ConnectionType type)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

bool	disconnect (const QMetaObject::Connection &connection)

bool	disconnect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method)

Public Attributes inherited from QObject
typedef	QObjectList

Protected Member Functions inherited from QObject
QObject *	sender () const const

int	senderSignalIndex () const const

int	receivers (const char *signal) const const

bool	isSignalConnected (const QMetaMethod &signal) const const

virtual void	timerEvent (QTimerEvent *event)

virtual void	childEvent (QChildEvent *event)

virtual void	customEvent (QEvent *event)

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	disconnectNotify (const QMetaMethod &signal)

Detailed Description

A class to define access to an API, with general settings.

This one is the base class of the API. You typically create one instance of it for each API you want to access, and then register it globally using registerGlobalApi().

The client is used by RestClass and other components, to get the basic request settings for all requests.

See also: RestClass, QtRestClient::addGlobalApi

Definition at line 30 of file restclient.h.

Member Enumeration Documentation

◆ DataMode

enum QtRestClient::RestClient::DataMode

strong

The different data modes in which the client can operate.

Enumerator
Cbor	The client expects and sends data in the binary CBOR format.
Json	The client expects and sends data in the textual JSON format.

Definition at line 62 of file restclient.h.

Member Function Documentation

◆ builder()

RequestBuilder RestClient::builder ( ) const

virtual

Creates a request builder with all the settings of this client.

Returns: A request builder, prepared with all the settings of the rest client

If you need to set additional properties on the builder, that are not provided by the rest client itself, you can override this function. To preserve all the properties override as follows:

RequestBuilder MyClient::builder() const override {
    return RestClient::builder()
        .set...
}

See also: RestClass::builder

Reimplemented in QtRestClient::Auth::AuthRestClient.

Definition at line 144 of file restclient.cpp.

◆ createClass()

RestClass * RestClient::createClass	(	const QString &	path,
		QObject *	parent = `nullptr`
	)

Creates a new rest class for the given path and parent.

Parameters

path	The path to be appended to the base path
parent	The parent for the created rest class

Returns: A newly created RestClass for the given path

The path will be appended to one created by the client. Please not that for all requests the request will be recreated. If you change any property of the RestClient, this will affect all RestClass instances that have been created by this client.

The following example shows how this affects the RestClass:

//client is configured as
client->setBaseUrl("https://api.example.com/default/");
client->addGlobalParameter("id", "42");
 
//class was created using
auto rClass = client->createClass("stuff/important", this);
 
//doing the following request
rClass->get<MyType>("test");
//will make a request to the URL: https://api.example.com/default/stuff/important/test?id=42
 
//after modifying the client and doing it again
client->setApiVersion(QVersionNumber(1));
rClass->get<MyType>("test");
//the URL becomes: https://api.example.com/default/v1/stuff/important/test?id=42

See also: RestClient::rootClass, QtRestClient::createApiClass

Definition at line 38 of file restclient.cpp.

◆ manager()

QNetworkAccessManager * RestClient::manager ( ) const

Returns the network access manager used by the restclient.

Returns: The network access manager used by the client

See also: RestClient::setManager

Definition at line 49 of file restclient.cpp.

◆ pagingFactory()

IPagingFactory * RestClient::pagingFactory ( ) const

Returns the paging factory used by the restclient.

Returns: The paging factory used by the client

See also: RestClient::setPagingFactory, IPaging, Paging

Definition at line 65 of file restclient.cpp.

◆ rootClass()

RestClass * RestClient::rootClass ( ) const

Returns the rest class with the root path.

Returns: The root class of this client

The root class is an instance of a RestClass, created with no extra path, parented to the client. You can use it to make requests, but you do not own it. You can create an equivalent copy of this instance, owned by you, by calling:

auto myRootClass = client->createClass(QString(), this);

See also: RestClient::createClass, QtRestClient::apiRootClass

Definition at line 43 of file restclient.cpp.

◆ serializer()

SerializerBase * RestClient::serializer ( ) const

Returns the json serializer used by the restclient.

Returns: The json serializer used by the client

See also: RestClient::setSerializer, https://skycoder42.github.io/QJsonSerializer

Definition at line 57 of file restclient.cpp.

◆ setManager

void RestClient::setManager ( QNetworkAccessManager * manager )

slot

Sets the network access manager to be used by all requests for this client.

Parameters

manager The network access manager to be used by the client

The client will take ownership of the manager. You must not delete it after setting it. All RestClass instances, requests, replies and more will use this new manager.

See also: RestClient::manager

Definition at line 172 of file restclient.cpp.

◆ setModernAttributes

void RestClient::setModernAttributes ( )

slot

Sets modern attributes in RestClient::requestAttributes.

The following attributes will be set on the client

Attribute	Value
QNetworkRequest::FollowRedirectsAttribute	`true`
QNetworkRequest::HttpPipeliningAllowedAttribute	`true`
QNetworkRequest::SpdyAllowedAttribute	`true`
QNetworkRequest::HTTP2AllowedAttribute	`true`

Note: While it is recommended to use these attributes, they may not all work for every backend. Older servers, for example, may have problems with HTTP2 requests, and will fail to even reply. In such cases, you can still use these attributes, and simply overwrite the problematic one again:

client->setModernAttributes()

client->addRequestAttribute(QNetworkRequest::HTTP2AllowedAttribute, false);

See also: RestClient::requestAttributes, QNetworkRequest::Attribute

Definition at line 290 of file restclient.cpp.

◆ setPagingFactory

void RestClient::setPagingFactory ( IPagingFactory * factory )

slot

Sets the paging factory to be used by all paging requests for this client.

Parameters

factory The paging factory to be used by the client

The client will take ownership of the factory. You must not delete it after setting it. All RestClass instances, requests, replies and more will use this new factory.

See also: RestClient::pagingFactory, IPaging, Paging, PagingFactory

Definition at line 198 of file restclient.cpp.

◆ setSerializer

void RestClient::setSerializer ( QtJsonSerializer::SerializerBase * serializer )

slot

Sets the json serializer to be used by all requests for this client.

Parameters

serializer The json serializer to be used by the client

The client will take ownership of the serializer. You must not delete it after setting it. All RestClass instances, requests, replies and more will use this new serializer.

See also: RestClient::serializer, https://skycoder42.github.io/QJsonSerializer

Definition at line 182 of file restclient.cpp.

Property Documentation

◆ apiVersion

QVersionNumber RestClient::apiVersion

readwrite

The version number to be appended to the path.

Default: none (default constructed)

The version will be directly appended to the baseUrl, if set. Trailing zeros are removed, and a "v" will be prepended to the number. If the version is invalid, it will not be added at all.

Example:
Assuming the baseUrl is https://example.com, we get the following urls:

Accessors
READ	apiVersion()
WRITE	setApiVersion()
NOTIFY	apiVersionChanged()

See also: RequestBuilder::setVersion

Definition at line 40 of file restclient.h.

◆ asyncPool

QThreadPool * RestClient::asyncPool

readwrite

Holds a thread pool to be used by all replies created via this clients classes.

Default: nullptr

By setting this property to any valid QThreadPool, all RestReply instances created by any RestClass that belongs to this client instance will have the RestReply::async property set to true and use this threadpool for their execution.

Note: This property implies RestClient::threaded and will automatically change it to true when set to a non nullptr value.

Warning: Please read the Multithreading section of the README before using the restclient in a threaded context.

Accessors
READ	asyncPool()
WRITE	setAsyncPool()
NOTIFY	asyncPoolChanged()

See also: RestClient::threaded, RestReply::async

Definition at line 57 of file restclient.h.

◆ baseUrl

QUrl RestClient::baseUrl

readwrite

The base URL to be used for every request to that api.

Default: invalid (default constructed)

All other settings regarding URLs will be based on this one.

Accessors
READ	baseUrl()
WRITE	setBaseUrl()
NOTIFY	baseUrlChanged()

See also: RequestBuilder

Definition at line 38 of file restclient.h.

◆ dataMode

RestClient::DataMode RestClient::dataMode

readwrite

The data mode the client is currently in.

Default: RestClient::DataMode::Json

The dataMode controls in which format data that is sent by the classes of this client and received by replies must be. Data can either be in JSON or in CBOR format, but cannot be mixed.

Note: Changing the dataMode will reset the internally used serializer. If you want to use a custom serializer, only set the serializer, not the dataMode, as the mode will be derived from the serializer.

Accessors
READ	dataMode()
WRITE	setDataMode()
WRITE	setSerializer() (indirectly)
NOTIFY	dataModeChanged()

See also: RestClient::setSerializer, RestClient::DataMode

Definition at line 36 of file restclient.h.

◆ globalHeaders

HeaderHash RestClient::globalHeaders

readwrite

A collection of headers to be added to every request.

Default: empty (default constructed)

Those headers are added for example to the HTTP-Requests as additional HTTP headers. Can be overwritten by the RestClass doing the request.

Accessors
READ	globalHeaders()
WRITE	setGlobalHeaders()
WRITE	addGlobalHeader() (indirectly)
WRITE	removeGlobalHeader() (indirectly)
NOTIFY	globalHeadersChanged()

See also: QNetworkRequest::setRawHeader, QNetworkRequest::KnownHeaders, RequestBuilder::addHeaders, RestClass

Definition at line 42 of file restclient.h.

◆ globalParameters

QUrlQuery RestClient::globalParameters

readwrite

A URL Query with parameters to be added to every request.

Default: empty (default constructed)

Can be overwritten by the RestClass doing the request.

Accessors
READ	globalParameters()
WRITE	setGlobalParameters()
WRITE	addGlobalParameter() (indirectly)
WRITE	removeGlobalParameter() (indirectly)
NOTIFY	globalParametersChanged()

See also: QUrl::setQuery(const QUrlQuery &), RequestBuilder::addParameters, RestClass

Definition at line 44 of file restclient.h.

◆ requestAttributes

QHash< QNetworkRequest::Attribute, QVariant > RestClient::requestAttributes

readwrite

A collection of attributes to be set on every request.

Default: empty (default constructed)

Can be overwritten by the RestClass doing the request. To use the recommended ones, call setModernAttributes()

Accessors
READ	requestAttributes()
WRITE	setRequestAttributes()
WRITE	addRequestAttribute() (indirectly)
WRITE	removeRequestAttribute() (indirectly)
NOTIFY	requestAttributesChanged()

See also: RestClient::setModernAttributes, QNetworkRequest::setAttribute, RequestBuilder::setAttributes

Definition at line 46 of file restclient.h.

◆ sslConfiguration

QSslConfiguration RestClient::sslConfiguration

readwrite

The SSL configuration to be used for HTTPS.

Default: QSslConfiguration::defaultConfiguration()

Can be overwritten by the RestClass doing the request. If you modify the applications default configuration after creating the rest client, those changes will not be applied to the existing client.

Accessors
READ	sslConfiguration()
WRITE	setSslConfiguration()
NOTIFY	sslConfigurationChanged()

See also: QSslConfiguration::setDefaultConfiguration, RequestBuilder::setSslConfig

Definition at line 52 of file restclient.h.

◆ threaded

QtRestClient::RestClient::threaded

readwrite

Specifies, whether the client can be used in a multithreaded context.

Default: false

By default, the restclient can only be accessed from the thread it was created in. By setting this property to true, it can be accessed globally from any thread.

Warning: Please read the Multithreading section of the README before using the restclient in a threaded context.

Accessors
READ	isThreaded()
WRITE	setThreaded()
NOTIFY	threadedChanged()

See also: RestClient::asyncPool, RequestBuilder::sendAsync

Definition at line 48 of file restclient.h.

The documentation for this class was generated from the following files:

restclient.h
restclient.dox
restclient.cpp

Public Types

Public Slots

Signals

Public Member Functions

Properties

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ DataMode

Member Function Documentation

◆ builder()

◆ createClass()

◆ manager()

◆ pagingFactory()

◆ rootClass()

◆ serializer()

◆ setManager

◆ setModernAttributes

◆ setPagingFactory

◆ setSerializer

Property Documentation

◆ apiVersion

◆ asyncPool

◆ baseUrl

◆ dataMode

◆ globalHeaders

◆ globalParameters

◆ requestAttributes

◆ sslConfiguration

◆ threaded