diff options
Diffstat (limited to 'examples/demos/colorpaletteclient/doc')
-rw-r--r-- | examples/demos/colorpaletteclient/doc/colorpaletteclient.rst | 79 | ||||
-rw-r--r-- | examples/demos/colorpaletteclient/doc/colorpaletteclient.webp | bin | 0 -> 28034 bytes |
2 files changed, 79 insertions, 0 deletions
diff --git a/examples/demos/colorpaletteclient/doc/colorpaletteclient.rst b/examples/demos/colorpaletteclient/doc/colorpaletteclient.rst new file mode 100644 index 000000000..0dcb91d4e --- /dev/null +++ b/examples/demos/colorpaletteclient/doc/colorpaletteclient.rst @@ -0,0 +1,79 @@ +RESTful API client +================== + +Example of how to create a RESTful API QML client. + +This example shows how to create a basic QML RESTful API client with an +imaginary color palette service. The application uses RESTful communication +with the selected server to request and send data. The REST service is provided +as a QML element whose child elements wrap the individual JSON data APIs +provided by the server. + +Application functionality +------------------------- + +The example provides the following basic functionalities: +* Select the server to communicate with +* List users and colors +* Login and logout users +* Modify and create new colors + +Server selection +---------------- + +At start the application presents the options for the color palette server to communicate +with. The predefined options are: + +* ``https://reqres.in``, a publicly available REST API test service +* A Qt-based REST API server example in ``QtHttpServer`` + +Once selected, the RESTful API client issues a test HTTP GET to the color API +to check if the service is accessible. + +One major difference between the two predefined API options is that the +Qt-based REST API server example is a stateful application which allows +modifying colors, whereas the ``reqres.in`` is a stateless API testing service. +In other words, when using the ``reqres.in`` backend, modifying the colors has +no lasting impact. + +The users and colors are paginated resources on the server-side. This means +that the server provides the data in chunks called pages. The UI listing +reflects this pagination and views the data on pages. + +Viewing the data on UI is done with standard QML views where the model are +QAbstractListModel-derived classes representing JSON data received from the +server. + +Logging in happens via the login function provided by the login popup. Under +the hood the login sends a HTTP POST request. Upon receiving a successful +response the authorization token is extracted from the response, which in turn +is then used in subsequent HTTP requests which require the token. + +Editing and adding new colors is done in a popup. Note that uploading the color +changes to the server requires that a user has logged in. + +REST implementation +------------------- + +The example illustrates one way to compose a REST service from individual resource elements. In +this example the resources are the paginated user and color resources plus the login service. +The resource elements are bound together by the base URL (server URL) and the shared network access +manager. + +The basis of the REST service is the RestService QML element whose children items +compose the actual service. + +Upon instantiation the RestService element loops its children elements and sets +them up to use the same network access manager. This way the individual +resources share the same access details such as the server URL and +authorization token. + +The actual communication is done with a rest access manager which implements +some convenience functionality to deal specifically with HTTP REST APIs and +effectively deals with sending and receiving the ``QNetworkRequest`` and +``QNetworkReply`` as needed. + +.. image:: colorpaletteclient.webp + :width: 90% + :align: center + :alt: RESTful API client diff --git a/examples/demos/colorpaletteclient/doc/colorpaletteclient.webp b/examples/demos/colorpaletteclient/doc/colorpaletteclient.webp Binary files differnew file mode 100644 index 000000000..8f4d9a621 --- /dev/null +++ b/examples/demos/colorpaletteclient/doc/colorpaletteclient.webp |