cpp-httplib isn‘t just for servers -- it also comes with a full HTTP client. Let’s use httplib::Client to send GET and POST requests.
To try out the client, you need a server that accepts requests. Save the following code, then compile and run it the same way you did in the previous chapter. We'll cover the server details in the next chapter.
#include "httplib.h" #include <iostream> int main() { httplib::Server svr; svr.Get("/hi", [](const auto &, auto &res) { res.set_content("Hello!", "text/plain"); }); svr.Get("/search", [](const auto &req, auto &res) { auto q = req.get_param_value("q"); res.set_content("Query: " + q, "text/plain"); }); svr.Post("/post", [](const auto &req, auto &res) { res.set_content(req.body, "text/plain"); }); svr.Post("/submit", [](const auto &req, auto &res) { std::string result; for (auto &[key, val] : req.params) { result += key + " = " + val + "\n"; } res.set_content(result, "text/plain"); }); svr.Post("/upload", [](const auto &req, auto &res) { auto f = req.form.get_file("file"); auto content = f.filename + " (" + std::to_string(f.content.size()) + " bytes)"; res.set_content(content, "text/plain"); }); svr.Get("/users/:id", [](const auto &req, auto &res) { auto id = req.path_params.at("id"); res.set_content("User ID: " + id, "text/plain"); }); svr.Get(R"(/files/(\d+))", [](const auto &req, auto &res) { auto id = req.matches[1]; res.set_content("File ID: " + std::string(id), "text/plain"); }); std::cout << "Listening on port 8080..." << std::endl; svr.listen("0.0.0.0", 8080); }
Once the server is running, open a separate terminal and give it a try. Let's start with the simplest GET request.
#include "httplib.h" #include <iostream> int main() { httplib::Client cli("http://localhost:8080"); auto res = cli.Get("/hi"); if (res) { std::cout << res->status << std::endl; // 200 std::cout << res->body << std::endl; // Hello! } }
Pass the server address to the httplib::Client constructor, then call Get() to send a request. You can retrieve the status code and body from the returned res.
Here's the equivalent curl command.
curl http://localhost:8080/hi # Hello!
A response contains header information in addition to the status code and body.
auto res = cli.Get("/hi"); if (res) { // Status code std::cout << res->status << std::endl; // 200 // Body std::cout << res->body << std::endl; // Hello! // Headers std::cout << res->get_header_value("Content-Type") << std::endl; // text/plain }
res->body is a std::string, so if you want to parse a JSON response, you can pass it directly to a JSON library like nlohmann/json.
To add query parameters to a GET request, you can either write them directly in the URL or use httplib::Params.
auto res = cli.Get("/search", httplib::Params{{"q", "cpp-httplib"}}); if (res) { std::cout << res->body << std::endl; // Query: cpp-httplib }
httplib::Params automatically URL-encodes special characters for you.
curl "http://localhost:8080/search?q=cpp-httplib" # Query: cpp-httplib
When values are embedded directly in the URL path, no special client API is needed. Just pass the path to Get() as-is.
auto res = cli.Get("/users/42"); if (res) { std::cout << res->body << std::endl; // User ID: 42 }
curl http://localhost:8080/users/42 # User ID: 42
The test server also has a /files/(\d+) route that uses a regex to accept numeric IDs only.
auto res = cli.Get("/files/42"); if (res) { std::cout << res->body << std::endl; // File ID: 42 }
curl http://localhost:8080/files/42 # File ID: 42
Pass a non-numeric ID like /files/abc and you‘ll get a 404. We’ll cover how that works in the next chapter.
To add custom HTTP headers, pass an httplib::Headers object. This works with both Get() and Post().
auto res = cli.Get("/hi", httplib::Headers{ {"Authorization", "Bearer my-token"} });
curl -H "Authorization: Bearer my-token" http://localhost:8080/hi
Let's POST some text data. Pass the body as the second argument to Post() and the Content-Type as the third.
auto res = cli.Post("/post", "Hello, Server!", "text/plain"); if (res) { std::cout << res->status << std::endl; // 200 std::cout << res->body << std::endl; // Hello, Server! }
The test server's /post endpoint echoes the body back, so you get the same string you sent.
curl -X POST -H "Content-Type: text/plain" -d "Hello, Server!" http://localhost:8080/post # Hello, Server!
You can send key-value pairs just like an HTML form. Use httplib::Params for this.
auto res = cli.Post("/submit", httplib::Params{ {"name", "Alice"}, {"age", "30"} }); if (res) { std::cout << res->body << std::endl; // age = 30 // name = Alice }
This sends the data in application/x-www-form-urlencoded format.
curl -X POST -d "name=Alice&age=30" http://localhost:8080/submit
To upload a file, use httplib::UploadFormDataItems to send it as multipart form data.
auto res = cli.Post("/upload", httplib::UploadFormDataItems{ {"file", "Hello, File!", "hello.txt", "text/plain"} }); if (res) { std::cout << res->body << std::endl; // hello.txt (12 bytes) }
Each element in UploadFormDataItems has four fields: {name, content, filename, content_type}.
curl -F "file=Hello, File!;filename=hello.txt;type=text/plain" http://localhost:8080/upload
Network communication can fail -- the server might not be reachable. Always check whether res is valid.
httplib::Client cli("http://localhost:9999"); // Non-existent port auto res = cli.Get("/hi"); if (!res) { // Connection error std::cout << "Error: " << httplib::to_string(res.error()) << std::endl; // Error: Connection return 1; } // If we reach here, we have a response if (res->status != 200) { std::cout << "HTTP Error: " << res->status << std::endl; return 1; } std::cout << res->body << std::endl;
There are two levels of errors.
res evaluates to false, and you can call res.error() to find out what went wrong.res evaluates to true, but you need to check res->status.Now you know how to send requests from a client. Next, let‘s take a closer look at the server side. We’ll dig into routing, path parameters, and more.
Next: Basic Server