How to Send an HTTP Request in C++: Cpr and libcurl Explained

cpp http-requests networking libcurl cpr
Cpp

Sending an HTTP request in C++ is famously verbose because the standard library doesn’t include networking out of the box, forcing developers to rely on third-party libraries for web communication.

What is an HTTP Request in C++?

In C++, an HTTP request is typically constructed by leveraging external libraries like libcurl or its modern C++ wrapper cpr (C++ Requests). Unlike higher-level languages where fetch or requests.get() are built-in, C++ requires you to explicitly manage the network buffers, handle socket connections, and deal with raw response payloads. Modern libraries wrap these low-level socket operations into more digestible abstractions, but you still need a foundational understanding of linking libraries and managing memory.

Why C++ Developers Need HTTP Requests

While C++ is often associated with systems programming and game engines, it frequently interacts with the web. Modern applications rely heavily on cloud services and remote configuration. For example, a high-performance trading platform built in C++ might need to query a REST API for real-time stock ticker updates. Similarly, an embedded IoT device programmed in C++ must securely POST telemetry data back to a centralized server. Another common use case is pulling configuration down from an AWS S3 bucket on application startup.

Basic Syntax

The most modern and pythonic way to make HTTP requests in C++ is using the cpr library (C++ Requests). It significantly reduces boilerplate compared to raw libcurl.

#include <iostream>
#include <cpr/cpr.h>

int main() {
    // 1. Send a synchronous GET request to the target URL
    cpr::Response r = cpr::Get(cpr::Url{"https://api.github.com/events"});
    
    // 2. Check the HTTP status code
    if (r.status_code == 200) {
        // 3. Print the raw response body (usually JSON or HTML)
        std::cout << "Response: " << r.text << std::endl;
    } else {
        std::cerr << "Error: " << r.status_code << std::endl;
    }
    return 0;
}

This snippet simply initializes a GET request to the GitHub API. It evaluates the response structure — which conveniently holds the HTTP status code, headers, and plain-text body — making it incredibly easy to debug and use immediately.

A Practical Example

In the real world, you rarely send basic GET requests without headers or parameters. Usually, you need to append authentication tokens (like a Bearer Token) and pass URL parameters. Here is a more realistic GET request.

#include <iostream>
#include <cpr/cpr.h>

void fetchUserData(int userId, const std::string& apiKey) {
    // 1. Build the request with parameters and authentication headers
    cpr::Response r = cpr::Get(
        cpr::Url{"https://api.example.com/users"},
        cpr::Parameters{{"id", std::to_string(userId)}},
        cpr::Header{{"Authorization", "Bearer " + apiKey}}
    );

    // 2. Safely handle the API response or connection failures
    if (r.status_code == 200) {
        std::cout << "User Data: " << r.text << "\n";
    } else if (r.status_code == 0) {
        // Status code 0 indicates a total failure to connect or resolve DNS
        std::cerr << "Network Error: " << r.error.message << "\n";
    } else {
        std::cerr << "API Error. Code: " << r.status_code << "\n";
    }
}

This function demonstrates passing dynamic query parameters and custom headers securely. The explicit check for a 0 status code is crucial in C++, as it indicates a library-level error (e.g. DNS failure) rather than a denied HTTP response from the server.

Common Mistakes

Mistake 1: Ignoring Connection Timeouts By default, some C++ HTTP libraries will wait indefinitely for a response if the server drops the connection but doesn’t send a RST packet. This will hang your application threads permanently. The Fix: Always set an explicit timeout. In cpr, append cpr::Timeout{5000} to your request parameters to fail gracefully after 5 seconds.

Mistake 2: Leaking Cleanups in Raw libcurl If you choose to use libcurl directly instead of a wrapper, developers often forget to call curl_easy_cleanup(curl) when an error occurs, leading to massive memory leaks during long-running tasks. The Fix: Use RAII (Resource Acquisition Is Initialization). Wrap your CURL handle in a std::unique_ptr with a custom deleter so it cleans itself up automatically when the function returns.

Mistake 3: Re-initializing SSL for Every Request Setting up TLS/SSL handshakes is incredibly CPU-intensive. Making 100 separate requests by fully reconstructing the HTTP object each time tanks performance. The Fix: Use connection pooling or multi-handle features (like cpr::Session) to keep the underlying TCP connection and SSL state open across multiple requests to the same host.

cpr vs. libcurl

The cpr library is essentially a well-designed, modern C++ wrapper around libcurl. You use cpr when developer velocity and readable code are your top priorities — it handles memory management and string conversions for you. You use raw libcurl when you are building an absolutely critical low-latency system, working inside a restricted environment with stringent dependency rules, or needing ultra-specific protocol features outside standard HTTP boundaries.

Under the Hood: Performance & Mechanics

When a C++ application executes a network request using libcurl or cpr, a complex OS interaction occurs. Setting up a request involves resolving the DNS address via system calls (which can block the thread if not done asynchronously). Once an IP is found, a TCP socket is created (socket()), and a three-way handshake (connect()) establishes the connection. If HTTPS is used, an additional TLS handshake calculates shared encryption keys using heavy asymmetric cryptography algorithms.

A hidden cost here is dynamic memory allocation. The response body is typically received in highly fragmented TCP packets (MTU is around 1500 bytes). Under the hood, the library dynamically resizes internal buffers (std::string or std::vector) using malloc() as more packets arrive. Frequent reallocations ruin CPU cache locality and trigger OS page faults. High-performance C++ systems bypass this by providing a pre-allocated fixed-size buffer to the network library as a write callback, strictly avoiding memory allocations during the hot loop of data reception.

Advanced Edge Cases

Edge Case 1: SNI (Server Name Indication) Failures on Virtual Hosts When connecting to an IP address directly or a CDN using strict virtual hosting, the TLS handshake might fail if the host header isn’t passed correctly during the TLS negotiation stage (before HTTP starts).

// Requires forcing the TLS SNI header even if the URL looks generic
cpr::Session session;
session.SetUrl(cpr::Url{"https://192.168.1.50/api"});
session.SetHeader(cpr::Header{{"Host", "api.internal.com"}});
// Some libraries require passing custom resolve parameters or explicit SNI flags here
cpr::Response r = session.Get();

If you omit the SNI routing configuration, the server’s load balancer will return a 403 or drop the TLS handshake.

Edge Case 2: Asynchronous Multi-Threading Data Races It is extremely easy to pass a dynamically allocated header or parameter string into a background HTTP thread, only for the main thread to deallocate it before the request completes.

std::string my_header = "TempToken123";
// Launching an async request and returning immediately
auto async_resp = cpr::GetAsync(cpr::Url{"https://api.dev"}, cpr::Header{{"Auth", my_header}});
// Undefined Behavior if my_header goes out of scope here while the thread still reads it!

The solution is to ensure by-value captures in your asynchronous lambdas or rely on thread-safe smart pointers for your payload data.

Testing HTTP Requests in C++

Testing network requests requires mocking to prevent flaky tests caused by real network outages. Using the widely adopted Google Test (gtest) framework, alongside a mock server library, is the standard approach to isolate logic.

#include <gtest/gtest.h>
#include <cpr/cpr.h>

// A mock networking interface
class NetworkInterface {
public:
    virtual cpr::Response get(const std::string& url) = 0;
};

// Our application logic under test
bool checkServerHealth(NetworkInterface& net) {
    auto r = net.get("https://api.xyz.com/health");
    return r.status_code == 200;
}

// In the test file:
TEST(HealthCheckTest, ReturnsTrueOn200) {
    MockNetworkInterface mockNet;
    // Assume we use Google Mock (gmock) to rig the return
    cpr::Response fakeResp;
    fakeResp.status_code = 200;
    EXPECT_CALL(mockNet, get("https://api.xyz.com/health"))
        .WillOnce(testing::Return(fakeResp));
        
    EXPECT_TRUE(checkServerHealth(mockNet));
}

This dependency injection approach avoids standing up a local Express server just to run your C++ unit tests, keeping your CI pipelines fast and deterministic.

Quick Reference

  • Library Choice: Use cpr (C++ Requests) for 90% of use cases; fall back to raw libcurl for hyper-optimized constraints.
  • Dependency Management: Requires CMake and linking against OpenSSL/BoringSSL for HTTPS support.
  • Resource Cleanup: If using raw libcurl, remember to cleanly drop handles to avoid memory bloat.
  • Always Error Check: HTTP 0 is a DNS/Socket error. HTTP 4xx/5xx are valid responses that imply application errors.

Next Steps

After mastering external communication, the logical next step is processing the response data efficiently in memory. You should explore How to Parse JSON in C++ to digest the payloads cleanly. Additionally, handling network delays gracefully without locking your main execution context is critical; look into Async/Await Patterns in C++ to optimize your application architecture.

Related Posts