diff --git a/README.md b/README.md
index 7b8edb1..b853cc5 100644
--- a/README.md
+++ b/README.md
@@ -1,30 +1,47 @@
-# 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. All backends expose the same `IConnection` API,
+so applications can choose the HTTP stack that best fits their existing dependencies.
-**Submodules:**
-This repository comes with submodules which are not necessary to build and use this project.
+## Requirements
-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.
+- 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 |
+| `CppRestAPI_CurlBackend=ON` | `` | `cpp_restapi::createCurlConnection()` | libcurl |
+| `CppRestAPI_CppHttplibBackend=ON` | `` | `cpp_restapi::createCppHttplibConnection()` | cpp-httplib |
+
+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.
## 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 simoultanously) and include `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 Curl 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)
```
@@ -37,14 +54,21 @@ target_link_libraries(app
)
```
-and that's all.
-
##### 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, configure with `-DCppRestAPI_JsonPagination=OFF`.
+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:
`cpp_restapi::GitHub::ConnectionBuilder` and `cpp_restapi::GitHub::Request`
@@ -53,26 +77,9 @@ 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).
-
-##### Standalone build:
-It is possible to build this project as any other regular CMake project by invoking:
-```bash
-cmake -B build
-cmake --build build
-```
-
-It can be usefull if you want to play with examples from `examples` dir or to run unit tests.
-
## Examples
-## Simplest usage
+### Simplest usage
```c++
#include
@@ -100,10 +107,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
@@ -135,7 +142,7 @@ int main(int argc, char** argv)
}
```
-cpp-httplib version:
+#### cpp-httplib version
```c++
#include
@@ -164,8 +171,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 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
@@ -174,6 +181,8 @@ However, for conveniance, there are also additional helpers available:
#include
#include
+#include
+
#include
#include
#include
@@ -185,7 +194,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();
@@ -194,18 +203,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
@@ -214,7 +227,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';
@@ -227,6 +240,8 @@ int main(int argc, char** argv)
```c++
#include
+#include
+
#include
#include
#include
@@ -235,7 +250,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';
@@ -244,7 +259,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)
@@ -252,13 +267,15 @@ 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
+### SSE with libcurl
```c++
#include
@@ -371,7 +388,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
@@ -447,7 +464,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",
@@ -477,11 +495,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
@@ -491,7 +509,7 @@ a compiler that supports ``.
| `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
@@ -526,19 +544,56 @@ int main()
}
```
-## Building examples
-Examples are located in the 'examples' directory of the project.
+## 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 `-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 `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.
-Please mind that setting `CppRestAPI_Examples` to `ON` will force all backends to be used.
+### Building unit tests
-## 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