From 28eb8fc5f7e8139f4cd8ff5fc4258920720ee5dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Walenciak?= Date: Sun, 26 Apr 2026 09:26:33 +0200 Subject: [PATCH 01/11] Clarify README build requirements --- README.md | 48 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 32 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 7b8edb1..2543f8a 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,23 @@ -# Rest API for c++ +# REST API for C++ -This is a c++ library originally written for accessing GitHub REST API v3. -Currently reorganized to be easily used with any Rest API available. +This is a C++ library originally written for accessing GitHub REST API v3. +It is now organized to work with any REST API. -It supports three backends for establishing connections with remote API servers: -Qt6/5, Curl and cpp-httplib. +It supports three interchangeable HTTP backends for connecting to remote API servers: +Qt 6/5, libcurl and cpp-httplib. + +## Requirements + +- CMake 3.16 or newer. +- A C++23 compiler. The public API uses C++23 library facilities such as `std::expected`. +- At least one HTTP backend must be enabled at configure time. + +| Backend option | Public factory header | Factory function | External dependency | +|-----------------------------------|---------------------------------------------------|---------------------------------------------|-----------------------------------------------------| +| `CppRestAPI_QtBackend=ON` | `` | `cpp_restapi::createQtConnection()` | Qt Network/Core, Qt 6 by default with Qt 5 fallback | +| `CppRestAPI_CurlBackend=ON` | `` | `cpp_restapi::createCurlConnection()` | libcurl | +| `CppRestAPI_CppHttplibBackend=ON` | `` | `cpp_restapi::createCppHttplibConnection()` | cpp-httplib | **Submodules:** This repository comes with submodules which are not necessary to build and use this project.
@@ -16,10 +28,10 @@ Visit https://learn.microsoft.com/vcpkg/about/privacy for more details. ## How to use it -This is a CMake based project and is meant to be included as a subproject. +This is a CMake-based project and is meant to be included as a subproject. Simply embed cpp_restapi's sources in your project, -choose which http backend you prefer (all can be used simoultanously) and include `cpp_restapi` project in your `CMakeLists.txt` like this: +choose which HTTP backend you prefer (all can be used simultaneously) and include the `cpp_restapi` project in your `CMakeLists.txt` like this: ```cmake set(CppRestAPI_QtBackend ON) # use this line if you prefer Qt backend @@ -44,7 +56,8 @@ and that's all. pagination strategy with JSON-aware merging (concatenates arrays, deep-merges objects). It is built by default (controlled by the `CppRestAPI_JsonPagination` CMake option) and adds a dependency on the `jsoncpp` library. To drop the -`jsoncpp` dependency entirely, configure with `-DCppRestAPI_JsonPagination=OFF`. +`jsoncpp` dependency entirely, disable both JSON pagination and GitHub helpers: +`-DCppRestAPI_GitHub=OFF -DCppRestAPI_JsonPagination=OFF`. ##### GitHub helpers: `cpp_restapi::GitHub::ConnectionBuilder` and `cpp_restapi::GitHub::Request` @@ -64,11 +77,14 @@ Set `CppRestAPI_UseQt5` CMake variable to `TRUE` to force Qt5 usage (in case bot ##### Standalone build: It is possible to build this project as any other regular CMake project by invoking: ```bash -cmake -B build +cmake -B build -DCppRestAPI_CurlBackend=ON cmake --build build ``` -It can be usefull if you want to play with examples from `examples` dir or to run unit tests. +Replace `CppRestAPI_CurlBackend` with another backend option if you prefer Qt or cpp-httplib. +At least one backend option must be enabled, otherwise configuration fails. + +It can be useful if you want to play with examples from the `examples` directory or run unit tests. ## Examples @@ -527,18 +543,18 @@ int main() ``` ## Building examples -Examples are located in the 'examples' directory of the project. +Examples are located in the `examples` directory of the project. To build them set `CppRestAPI_Examples` CMake variable to `ON`. -It can be done when invoking `cmake` command by providing `-DCppRestAPI_Examples=ON` command line argument (see `Standalone build` section). -Or by modifying entry `CppRestAPI_Examples` in CMakeCache.txt file located in build directory of an already configured project. +It can be done when invoking `cmake` command by providing the `-DCppRestAPI_Examples=ON` command-line argument (see the `Standalone build` section), +or by modifying the `CppRestAPI_Examples` entry in the `CMakeCache.txt` file located in the build directory of an already configured project. -Please mind that setting `CppRestAPI_Examples` to `ON` will force all backends to be used. +Please mind that setting `CppRestAPI_Examples` to `ON` forces all backends and optional components to be used, so all backend dependencies must be available. ## Building unit tests -Unit tests are located in 'tests' directory of the project. +Unit tests are located in the `tests` directory of the project. To build them set `CppRestAPI_Tests` CMake variable to `ON`. -Please mind that setting `CppRestAPI_Tests` to `ON` will force all backends to be used. +Please mind that setting `CppRestAPI_Tests` to `ON` forces all backends and optional components to be used, so all backend dependencies must be available. ## Links From 02a71a80f9b9797d599a6cf00d5dc2ef9f85f636 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Walenciak?= Date: Sun, 26 Apr 2026 09:27:10 +0200 Subject: [PATCH 02/11] Fix GitHub helper README examples --- README.md | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 2543f8a..ed53a94 100644 --- a/README.md +++ b/README.md @@ -180,8 +180,8 @@ int main(int argc, char** argv) ### Dedicated GitHub helpers -For accessing GitHub API it is possible to use exactly the same apporach as presented above.
-However, for conveniance, there are also additional helpers available: +For accessing GitHub API it is possible to use exactly the same approach as presented above.
+However, for convenience, there are also additional helpers available: #### Qt example @@ -190,6 +190,8 @@ However, for conveniance, there are also additional helpers available: #include #include +#include + #include #include #include @@ -201,7 +203,7 @@ int main(int argc, char** argv) QNetworkAccessManager manager; auto connection = cpp_restapi::GitHub::ConnectionBuilder().build(cpp_restapi::createQtConnection, manager); - cpp_restapi::GitHub::Request request(connection); + cpp_restapi::GitHub::Request request(std::move(connection)); qInfo() << request.getRateLimit().c_str(); qInfo() << request.getUserInfo("Kicer86").c_str(); @@ -210,18 +212,22 @@ int main(int argc, char** argv) } ``` -Here connection is being build with `ConnectionBuilder`.
-Builder provides methods for setting additional connection parameters (passed as a second argument to `Connection` after API url).
-It also sets the API url automatically.
-Refer documentation of `ConnectionBuilder` for more details. +Here the connection is built with `ConnectionBuilder`.
+The builder sets the GitHub API URL and headers automatically. +When calling `build(factory, args...)`, any backend-specific arguments are forwarded to the factory before the URL and headers. +For example, the Qt factory receives the `QNetworkAccessManager` first. +The returned `std::unique_ptr` is then moved into `GitHub::Request`, which owns the connection. +Refer to the documentation of `ConnectionBuilder` for more details. -Additionaly there is also `cpp_restapi::GitHub::Request` class available which comes with accessors to most common API requests. +The `cpp_restapi::GitHub::Request` class provides accessors for the most common GitHub API requests. #### libcurl example ```c++ #include +#include + #include #include #include @@ -230,7 +236,7 @@ Additionaly there is also `cpp_restapi::GitHub::Request` class available which c int main(int argc, char** argv) { auto connection = cpp_restapi::GitHub::ConnectionBuilder().build(cpp_restapi::createCurlConnection); - cpp_restapi::GitHub::Request request(connection); + cpp_restapi::GitHub::Request request(std::move(connection)); std::cout << request.getRateLimit() << '\n'; std::cout << request.getUserInfo("Kicer86") << '\n'; @@ -243,6 +249,8 @@ int main(int argc, char** argv) ```c++ #include +#include + #include #include #include @@ -251,7 +259,7 @@ int main(int argc, char** argv) int main(int argc, char** argv) { auto connection = cpp_restapi::GitHub::ConnectionBuilder().build(cpp_restapi::createCppHttplibConnection); - cpp_restapi::GitHub::Request request(connection); + cpp_restapi::GitHub::Request request(std::move(connection)); std::cout << request.getRateLimit() << '\n'; std::cout << request.getUserInfo("Kicer86") << '\n'; From 7d94ccd7ae92fbc221ed8e201044d52c5f04a985 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Walenciak?= Date: Sun, 26 Apr 2026 09:27:27 +0200 Subject: [PATCH 03/11] Clarify README async behavior --- README.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index ed53a94..95ea3e7 100644 --- a/README.md +++ b/README.md @@ -276,11 +276,13 @@ In addition to regular REST requests, the library supports [Server-Sent Events](https://html.spec.whatwg.org/multipage/server-sent-events.html) — a standard mechanism for receiving a stream of events from a server over HTTP. -SSE support is available for all three backends via `Connection::subscribe()`. +SSE support is available for all three backends via `IConnection::subscribe()`. The method connects to an SSE endpoint, delivers parsed events through a callback and returns an `ISseConnection` handle. The call is non-blocking — events are received on an internal thread (or via the Qt event loop for the Qt backend). Use `close()` to stop. +Keep the returned `ISseConnection` alive for as long as you want to receive events. +For the Qt backend, the Qt event loop must be running. ### SSE with curl @@ -471,7 +473,8 @@ int main(int argc, char** argv) ### Cancellation The `CancellationToken` returned by async `fetch()` is a `std::shared_ptr>`. -Setting it to `true` suppresses further callbacks: +Setting it to `true` suppresses further callbacks. It does not guarantee that an already-started +network request is aborted immediately: ```c++ auto cancel = connection->fetch("slow/endpoint", @@ -501,11 +504,11 @@ auto cancel = connection->fetch("repos/owner/repo/issues", strategy, }); ``` -## C++20 Coroutine Helpers +## Coroutine Helpers The header-only `` provides lightweight coroutine -wrappers around the callback-based async API. It requires C++20 (or later) and -a compiler that supports ``. +wrappers around the callback-based async API. The project requires C++23, and +the coroutine helpers also require compiler support for ``. ### Key types From 10d62d659f736d3388b7cf819ea2a1dda87bc795 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Walenciak?= Date: Sun, 26 Apr 2026 09:27:47 +0200 Subject: [PATCH 04/11] Document vcpkg README workflow --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index 95ea3e7..121ee5a 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,16 @@ As of now the only submodule is `vcpkg` which can simplify build by providing re Please mind that vcpkg uses **telemetry**.
Visit https://learn.microsoft.com/vcpkg/about/privacy for more details. +If you want to use the bundled vcpkg checkout, initialize it and configure CMake with the vcpkg toolchain file: + +```bash +git submodule update --init vcpkg +./vcpkg/bootstrap-vcpkg.sh +cmake -B build -DCMAKE_TOOLCHAIN_FILE=$PWD/vcpkg/scripts/buildsystems/vcpkg.cmake -DCppRestAPI_CppHttplibBackend=ON +``` + +The repository also provides vcpkg-based CMake presets in `CMakePresets.json`. + ## How to use it This is a CMake-based project and is meant to be included as a subproject. From 053c620299cbb8b3e9363ca88d5605ade8968464 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Walenciak?= Date: Sun, 26 Apr 2026 09:28:05 +0200 Subject: [PATCH 05/11] Polish README wording --- README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 121ee5a..0b9a8a3 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ choose which HTTP backend you prefer (all can be used simultaneously) and includ ```cmake set(CppRestAPI_QtBackend ON) # use this line if you prefer Qt backend -set(CppRestAPI_CurlBackend ON) # use this line if you prefer Curl backend +set(CppRestAPI_CurlBackend ON) # use this line if you prefer libcurl backend set(CppRestAPI_CppHttplibBackend ON) # use this line if you prefer cpp-httplib backend add_subdirectory(cpp_restapi) ``` @@ -59,7 +59,7 @@ target_link_libraries(app ) ``` -and that's all. +That is enough to link your application against the library. ##### JSON-aware pagination: `cpp_restapi::LinkHeaderPaginationStrategy` is an RFC 5988 `Link`-header based @@ -98,7 +98,7 @@ It can be useful if you want to play with examples from the `examples` directory ## Examples -## Simplest usage +### Simplest usage ```c++ #include @@ -126,10 +126,10 @@ int main(int argc, char** argv) } ``` -This example accesses The Star Wars API using curl backend.
+This example accesses The Star Wars API using the libcurl backend.
`fetch()` returns `std::expected` — on success the response body is available via `value()`, on failure the `HttpError` carries the HTTP status code, response body and a human-readable message. -Qt version: +#### Qt version ```c++ #include #include @@ -161,7 +161,7 @@ int main(int argc, char** argv) } ``` -cpp-httplib version: +#### cpp-httplib version ```c++ #include @@ -190,7 +190,7 @@ int main(int argc, char** argv) ### Dedicated GitHub helpers -For accessing GitHub API it is possible to use exactly the same approach as presented above.
+For accessing the GitHub API it is possible to use exactly the same approach as presented above.
However, for convenience, there are also additional helpers available: #### Qt example @@ -278,7 +278,7 @@ int main(int argc, char** argv) } ``` -Also please look into 'examples' directory for details. +See the `examples` directory for complete example programs. ## Server-Sent Events (SSE) @@ -294,7 +294,7 @@ thread (or via the Qt event loop for the Qt backend). Use `close()` to stop. Keep the returned `ISseConnection` alive for as long as you want to receive events. For the Qt backend, the Qt event loop must be running. -### SSE with curl +### SSE with libcurl ```c++ #include @@ -407,7 +407,7 @@ before they fire. For non-Qt backends (curl, cpp-httplib) callbacks run on a background `std::thread`. For the Qt backend, callbacks are invoked on the Qt event-loop thread. -### Async with curl +### Async with libcurl ```c++ #include @@ -528,7 +528,7 @@ the coroutine helpers also require compiler support for ``. | `coFetch(conn, request)` | Returns an awaitable yielding `std::expected`. | | `coFetch(conn, request, strategy)` | Returns an awaitable yielding `std::expected` (paginated). | -### Example (curl backend) +### Example (libcurl backend) ```c++ #include From b63978a7d20ece9a4723f252549887239cf7a829 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Walenciak?= Date: Sun, 26 Apr 2026 09:58:25 +0200 Subject: [PATCH 06/11] Move standalone README docs below examples --- README.md | 74 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 41 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 0b9a8a3..89a7e0c 100644 --- a/README.md +++ b/README.md @@ -19,26 +19,9 @@ Qt 6/5, libcurl and cpp-httplib. | `CppRestAPI_CurlBackend=ON` | `` | `cpp_restapi::createCurlConnection()` | libcurl | | `CppRestAPI_CppHttplibBackend=ON` | `` | `cpp_restapi::createCppHttplibConnection()` | cpp-httplib | -**Submodules:** -This repository comes with submodules which are not necessary to build and use this project.
- -As of now the only submodule is `vcpkg` which can simplify build by providing required dependencies.
-Please mind that vcpkg uses **telemetry**.
-Visit https://learn.microsoft.com/vcpkg/about/privacy for more details. - -If you want to use the bundled vcpkg checkout, initialize it and configure CMake with the vcpkg toolchain file: - -```bash -git submodule update --init vcpkg -./vcpkg/bootstrap-vcpkg.sh -cmake -B build -DCMAKE_TOOLCHAIN_FILE=$PWD/vcpkg/scripts/buildsystems/vcpkg.cmake -DCppRestAPI_CppHttplibBackend=ON -``` - -The repository also provides vcpkg-based CMake presets in `CMakePresets.json`. - ## How to use it -This is a CMake-based project and is meant to be included as a subproject. +This is a CMake-based project and is primarily meant to be included as a subproject. Simply embed cpp_restapi's sources in your project, choose which HTTP backend you prefer (all can be used simultaneously) and include the `cpp_restapi` project in your `CMakeLists.txt` like this: @@ -84,18 +67,6 @@ If no Qt6 is found, an automatic fallback to Qt5 will happen. Set `CppRestAPI_UseQt5` CMake variable to `TRUE` to force Qt5 usage (in case both versions are available). -##### Standalone build: -It is possible to build this project as any other regular CMake project by invoking: -```bash -cmake -B build -DCppRestAPI_CurlBackend=ON -cmake --build build -``` - -Replace `CppRestAPI_CurlBackend` with another backend option if you prefer Qt or cpp-httplib. -At least one backend option must be enabled, otherwise configuration fails. - -It can be useful if you want to play with examples from the `examples` directory or run unit tests. - ## Examples ### Simplest usage @@ -563,15 +534,52 @@ int main() } ``` -## Building examples +## Standalone builds, examples and tests + +Standalone builds are mostly useful when you want to run the examples or unit tests from this repository. +The main integration scenario is still to include cpp_restapi as a CMake subproject. + +### Basic standalone build + +It is possible to build this project as any other regular CMake project by invoking: + +```bash +cmake -B build -DCppRestAPI_CurlBackend=ON +cmake --build build +``` + +Replace `CppRestAPI_CurlBackend` with another backend option if you prefer Qt or cpp-httplib. +At least one backend option must be enabled, otherwise configuration fails. + +### Using bundled vcpkg + +This repository has an optional `vcpkg` submodule. It is not required when you include cpp_restapi as a subproject, +but it can simplify standalone builds by providing dependencies. + +Please mind that vcpkg uses **telemetry**.
+Visit https://learn.microsoft.com/vcpkg/about/privacy for more details. + +If you want to use the bundled vcpkg checkout, initialize it and configure CMake with the vcpkg toolchain file: + +```bash +git submodule update --init vcpkg +./vcpkg/bootstrap-vcpkg.sh +cmake -B build -DCMAKE_TOOLCHAIN_FILE=$PWD/vcpkg/scripts/buildsystems/vcpkg.cmake -DCppRestAPI_CppHttplibBackend=ON +``` + +The repository also provides vcpkg-based CMake presets in `CMakePresets.json`. + +### Building examples + Examples are located in the `examples` directory of the project. To build them set `CppRestAPI_Examples` CMake variable to `ON`. -It can be done when invoking `cmake` command by providing the `-DCppRestAPI_Examples=ON` command-line argument (see the `Standalone build` section), +It can be done when invoking `cmake` command by providing the `-DCppRestAPI_Examples=ON` command-line argument (see the `Basic standalone build` section), or by modifying the `CppRestAPI_Examples` entry in the `CMakeCache.txt` file located in the build directory of an already configured project. Please mind that setting `CppRestAPI_Examples` to `ON` forces all backends and optional components to be used, so all backend dependencies must be available. -## Building unit tests +### Building unit tests + Unit tests are located in the `tests` directory of the project. To build them set `CppRestAPI_Tests` CMake variable to `ON`. From 1fe722f74f33129d9609a1a2f0df1a084a30a576 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Walenciak?= Date: Sun, 26 Apr 2026 10:11:44 +0200 Subject: [PATCH 07/11] Drop redundant information --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 89a7e0c..99dfdea 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,6 @@ target_link_libraries(app ) ``` -That is enough to link your application against the library. ##### JSON-aware pagination: `cpp_restapi::LinkHeaderPaginationStrategy` is an RFC 5988 `Link`-header based From 371685aafbb74c846cf4a3777967efb8ff95e4f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Walenciak?= Date: Sun, 26 Apr 2026 10:12:21 +0200 Subject: [PATCH 08/11] Explain README pagination rationale --- README.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 99dfdea..6d10938 100644 --- a/README.md +++ b/README.md @@ -46,9 +46,17 @@ target_link_libraries(app ##### JSON-aware pagination: `cpp_restapi::LinkHeaderPaginationStrategy` is an RFC 5988 `Link`-header based pagination strategy with JSON-aware merging (concatenates arrays, deep-merges -objects). It is built by default (controlled by the `CppRestAPI_JsonPagination` -CMake option) and adds a dependency on the `jsoncpp` library. To drop the -`jsoncpp` dependency entirely, disable both JSON pagination and GitHub helpers: +objects). + +This is useful for REST APIs that split large list responses into pages. For example, +GitHub returns only one page of issues, releases or repositories at a time and exposes +the next page through the HTTP `Link` header. The pagination strategy lets the library +follow those links and return one merged response instead of forcing each caller to +repeat the same "read header, fetch next page, merge JSON" loop. + +It is built by default (controlled by the `CppRestAPI_JsonPagination` CMake option) +because the GitHub helpers use it for paginated endpoints. It adds a dependency on the +`jsoncpp` library. To drop the `jsoncpp` dependency entirely, disable both JSON pagination and GitHub helpers: `-DCppRestAPI_GitHub=OFF -DCppRestAPI_JsonPagination=OFF`. ##### GitHub helpers: From 3198845c4612d3a16a93e66662ba79dd0d831fcb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Walenciak?= Date: Sun, 26 Apr 2026 10:13:49 +0200 Subject: [PATCH 09/11] Format --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 6d10938..062a6d0 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,6 @@ target_link_libraries(app ) ``` - ##### JSON-aware pagination: `cpp_restapi::LinkHeaderPaginationStrategy` is an RFC 5988 `Link`-header based pagination strategy with JSON-aware merging (concatenates arrays, deep-merges From ffc1c8c416a1fddaa0d4160fc10e618f59762a76 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Walenciak?= Date: Sun, 26 Apr 2026 10:16:07 +0200 Subject: [PATCH 10/11] Move backend dependency note to requirements --- README.md | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 062a6d0..531e1d6 100644 --- a/README.md +++ b/README.md @@ -13,11 +13,17 @@ Qt 6/5, libcurl and cpp-httplib. - A C++23 compiler. The public API uses C++23 library facilities such as `std::expected`. - At least one HTTP backend must be enabled at configure time. -| Backend option | Public factory header | Factory function | External dependency | -|-----------------------------------|---------------------------------------------------|---------------------------------------------|-----------------------------------------------------| -| `CppRestAPI_QtBackend=ON` | `` | `cpp_restapi::createQtConnection()` | Qt Network/Core, Qt 6 by default with Qt 5 fallback | -| `CppRestAPI_CurlBackend=ON` | `` | `cpp_restapi::createCurlConnection()` | libcurl | -| `CppRestAPI_CppHttplibBackend=ON` | `` | `cpp_restapi::createCppHttplibConnection()` | cpp-httplib | +| Backend option | Public factory header | Factory function | External dependency | +|-----------------------------------|---------------------------------------------------|---------------------------------------------|---------------------| +| `CppRestAPI_QtBackend=ON` | `` | `cpp_restapi::createQtConnection()` | Qt Network/Core | +| `CppRestAPI_CurlBackend=ON` | `` | `cpp_restapi::createCurlConnection()` | libcurl | +| `CppRestAPI_CppHttplibBackend=ON` | `` | `cpp_restapi::createCppHttplibConnection()` | cpp-httplib | + +Only dependencies for the backends you enable need to be available to CMake. +If you enable multiple backends, all corresponding dependencies must be available. + +The Qt backend uses Qt 6 by default and falls back to Qt 5 when Qt 6 is not found. +Set `CppRestAPI_UseQt5` CMake variable to `TRUE` to force Qt 5 usage when both versions are available. ## How to use it @@ -65,14 +71,6 @@ are convenience wrappers for the GitHub REST API. They are built by default enables `CppRestAPI_JsonPagination`). Disable with `-DCppRestAPI_GitHub=OFF` if not needed. -##### Note: -Depending on your choice of backend you may need to install libcurl, Qt and/or cpp-httplib libraries. - -Qt backend can be compiled with Qt6 (default) or Qt5. -If no Qt6 is found, an automatic fallback to Qt5 will happen. - -Set `CppRestAPI_UseQt5` CMake variable to `TRUE` to force Qt5 usage (in case both versions are available). - ## Examples ### Simplest usage From efdd39805bb8dfc6437f8c19c7c823785b917196 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Walenciak?= Date: Sun, 26 Apr 2026 10:19:33 +0200 Subject: [PATCH 11/11] Clarify backend selection guidance --- README.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 531e1d6..b853cc5 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,8 @@ This is a C++ library originally written for accessing GitHub REST API v3. It is now organized to work with any REST API. It supports three interchangeable HTTP backends for connecting to remote API servers: -Qt 6/5, libcurl and cpp-httplib. +Qt 6/5, libcurl and cpp-httplib. All backends expose the same `IConnection` API, +so applications can choose the HTTP stack that best fits their existing dependencies. ## Requirements @@ -19,8 +20,12 @@ Qt 6/5, libcurl and cpp-httplib. | `CppRestAPI_CurlBackend=ON` | `` | `cpp_restapi::createCurlConnection()` | libcurl | | `CppRestAPI_CppHttplibBackend=ON` | `` | `cpp_restapi::createCppHttplibConnection()` | cpp-httplib | -Only dependencies for the backends you enable need to be available to CMake. -If you enable multiple backends, all corresponding dependencies must be available. +Typical applications enable one backend: for example, Qt applications usually use the Qt backend, +while non-Qt applications can choose libcurl or cpp-httplib. Multiple backends can be enabled in +one build because each backend provides its own factory function behind the same `IConnection` +interface. This is mainly useful for examples, tests or comparing backends rather than for normal +application builds. If you do enable more than one backend, all corresponding dependencies must be +available to CMake. The Qt backend uses Qt 6 by default and falls back to Qt 5 when Qt 6 is not found. Set `CppRestAPI_UseQt5` CMake variable to `TRUE` to force Qt 5 usage when both versions are available. @@ -30,12 +35,13 @@ Set `CppRestAPI_UseQt5` CMake variable to `TRUE` to force Qt 5 usage when both v This is a CMake-based project and is primarily meant to be included as a subproject. Simply embed cpp_restapi's sources in your project, -choose which HTTP backend you prefer (all can be used simultaneously) and include the `cpp_restapi` project in your `CMakeLists.txt` like this: +choose the HTTP backend you want to use and include the `cpp_restapi` project in your `CMakeLists.txt` like this: ```cmake -set(CppRestAPI_QtBackend ON) # use this line if you prefer Qt backend -set(CppRestAPI_CurlBackend ON) # use this line if you prefer libcurl backend -set(CppRestAPI_CppHttplibBackend ON) # use this line if you prefer cpp-httplib backend +# Pick one backend for a typical application. +set(CppRestAPI_CurlBackend ON) # libcurl backend +# set(CppRestAPI_QtBackend ON) # Qt backend +# set(CppRestAPI_CppHttplibBackend ON) # cpp-httplib backend add_subdirectory(cpp_restapi) ```