restcl: A Focused REST Client for Modern C++

restcl is a header-only Modern C++23 REST client library designed with nlohmann::json as a first-class API metaphor for interacting with RESTful servers.

• Cross-Platform Native IO: Uses native WinHTTP on Windows (WinHttpRESTClient) and libcurl on Linux/macOS (HttpRESTClient).
• Factory Function: siddiqsoft::GetRESTClient() automatically returns the optimal client instance for the target platform.
• Expressive Request Syntax: Native user-defined literals like "https://api.example.com/endpoint"_GET.
• JSON-First API: Request headers, parameters, and bodies are represented as nlohmann::json objects.

---

Documentation Site

Full guides, tutorials, API specifications, and interactive dependency graphs are hosted on our documentation site:

• 🚀 Features & Usage: User-defined literals, JSON API metaphor, async callbacks.
• 📦 Integration & CMake: add_subdirectory, CPM, FetchContent, build options, testing.
• 📊 Dependency Graph: Automated visual dependency diagram and version matrix.
• 📖 API Reference: Specifications for GetRESTClient, rest_request, rest_response, and client classes.
• 💡 Examples: Standalone applications including the Cosmos Probes service health probe.

---

Quick Start

#include "siddiqsoft/restcl.hpp"

using namespace siddiqsoft;
using namespace siddiqsoft::restcl_literals;

int main()
{
    // Instantiates WinHttpRESTClient on Windows or HttpRESTClient on Linux/macOS
    auto client = GetRESTClient({
        {"userAgent", "my-app/1.0"},
        {"timeout", 5000}
    });

    // 1. Simple GET request using literal operator
    auto response = client->send("https://httpbin.org/get"_GET);
    if (response && response->success()) {
        std::cout << "Response body: " << response->content->body << std::endl;
    }

    // 2. POST request with custom headers and JSON body
    auto req = "https://httpbin.org/post"_POST;
    req.headers["X-Custom-Header"] = "my-header-value";
    req.setContent({ {"name", "Modern C++"}, {"version", 23} });

    auto postResponse = client->send(req);
    if (postResponse && postResponse->success()) {
        std::cout << "Status: " << postResponse->statusCode() << std::endl;
    }

    return 0;
}

---

Integration

Using CPM / FetchContent

CPMAddPackage("gh:SiddiqSoft/restcl#2.3.12")
target_link_libraries(${PROJECT_NAME} INTERFACE siddiqsoft::restcl)

Git Submodule

git submodule add https://github.com/SiddiqSoft/restcl.git vendor/restcl

add_subdirectory(vendor/restcl)
target_link_libraries(your_target PRIVATE siddiqsoft::restcl)

For full setup guides and NuGet usage, view the Integration Guide.

---

Requirements & Building

Requirement	Details
Language Standard	C++23 (/std:c++latest on MSVC, -std=c++23 on Clang/GCC)
Platforms	Windows (MSVC 2022+), Linux (GCC 11+, Clang 13+), macOS (Apple Clang 13+)
Dependencies	nlohmann/json, SplitUri, AzureCppUtils, ctre

Building with CMake Presets

# Configure with a preset matching your OS/compiler (e.g. Darwin, Linux-GCC, Windows-x64)
cmake --preset Darwin

# Build target
cmake --build --preset Darwin

# Run test suite
ctest --preset Darwin

---

License

Licensed under the MIT License.