ColorPalette RESTful API client

This example demonstrates how to use the Qt6 OpenAPI generator to create RESTful API client code from the colorpalette.yaml specification and integrate it into a QML application. Its structure and UI closely match the Qt Quick Demo - RESTful API client example so that the differences in the networking and integration approach are easy to identify.

Running the Example

To run the example from Qt Creator, open the Welcome mode and select the example from Examples. For more information, see Qt Creator: Tutorial: Build and run.

Application functionality

The example provides the same basic functionalities as Qt Quick Demo - RESTful API client.

Server selection

At startup, the application presents a predefined server option that the Color Palette client can communicate with:

• Qt-based REST API server example in QtHttpServer

Once the server is selected and the Connect button is pressed, the RESTful API client issues a test HTTP GET request to verify that the server is available. If the server is not running, the application remains on the server selection view.

Generating client code from an OpenAPI specification

The Qt6 OpenAPI generator is invoked from the CMakeLists.txt file to generate client code from the colorpalette.yaml specification by calling the qt6_add_openapi_client macro.

qt6_add_openapi_client(ColorpaletteClientExample
    SPEC_FILE
        ${CMAKE_CURRENT_SOURCE_DIR}/colorpalette.yaml
)

The generated API classes ColorsApi and UsersApi handle all the low-level HTTP details:

• Server configuration
• HTTP request construction for all standard HTTP methods
• Serialization of input parameters according to the specification
• Deserialization of server responses into typed objects
• Success and errors are reported via Qt signals

Compared to the other version of the example that uses the QtNetworkAuth APIs directly, this approach allows you to avoid manually constructing and sending the network requests.

Exposing generated APIs to QML

The generated API classes ColorsApi and UsersApi are exposed to QML via helper classes defined in ApiBridges.h. Each helper uses the QML_FOREIGN macro and registers the underlying C++ instance as a singleton, allowing QML to access the same object while ownership remains in C++. For more details on this topic, check the Qt QML documentation on exposing an existing object as a singleton.

struct ForeignColorsAPI
{
    Q_GADGET
    QML_FOREIGN(QtOpenAPI::ColorsApi)
    QML_SINGLETON
    QML_NAMED_ELEMENT(ColorsApi)

};

Using the APIs from QML

Once registered, the APIs are available globally in QML. This allows QML components to directly access ColorsApi and UsersApi and call their methods, as shown below:

ColorsApi.getColors(page)

Each API method emits signals when the operation succeeds or fails, allowing QML components to handle the server responses:

function onAddColorFinished() {
    root.fetchColors(root.currentColorPage)
}

function onAddColorErrorOccurred(errorType, errorStr) {
    root.handleError(errorStr)
}

Helper singleton types

Some API methods take non-trivial types as parameters, such as Credentials and Color. The example provides QML singletons to construct instances of such types in ApiBridges.h:

class Credentials: public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON
public:
    Q_INVOKABLE QtOpenAPI::Credentials create(const QString &email, const QString &password)
    {
        QtOpenAPI::Credentials credentials;
        credentials.setEmail(email);
        credentials.setPassword(password);
        return credentials;
    }
};

These singletons can then be used in QML when calling API methods. For example, Credentials is used to create a credentials object before logging in:

var credentials = Credentials.create(userInfo.model.email,
                                          "apassword");
UsersApi.loginUser(credentials);

Source files

Example project @ code.qt.io