C++ client for making HTTP/REST requests


REST client for C++

Build Status Coverage Status Packagecloud doxygen MIT license


This is a simple REST client for C++. It wraps libcurl for HTTP requests.


restclient-cpp provides two ways of interacting with REST endpoints. There is a simple one, which doesn't need you to configure an object to interact with an API. However the simple way doesn't provide a lot of configuration options either. So if you need more than just a simple HTTP call, you will probably want to check out the advanced usage.

Simple Usage

The simple API is just some static methods modeled after the most common HTTP verbs:

#include "restclient-cpp/restclient.h"

RestClient::Response r = RestClient::get("http://url.com")
RestClient::Response r = RestClient::post("http://url.com/post", "application/json", "{\"foo\": \"bla\"}")
RestClient::Response r = RestClient::put("http://url.com/put", "application/json", "{\"foo\": \"bla\"}")
RestClient::Response r = RestClient::patch("http://url.com/patch", "application/json", "{\"foo\": \"bla\"}")
RestClient::Response r = RestClient::del("http://url.com/delete")
RestClient::Response r = RestClient::head("http://url.com")
RestClient::Response r = RestClient::options("http://url.com")

The response is of type RestClient::Response and has three attributes:

RestClient::Response.code // HTTP response code
RestClient::Response.body // HTTP response body
RestClient::Response.headers // HTTP response headers

Advanced Usage

However if you want more sophisticated features like connection reuse, timeouts or authentication, there is also a different, more configurable way.

#include "restclient-cpp/connection.h"
#include "restclient-cpp/restclient.h"

// initialize RestClient

// get a connection object
RestClient::Connection* conn = new RestClient::Connection("http://url.com");

// configure basic auth
conn->SetBasicAuth("WarMachine68", "WARMACHINEROX");

// set connection timeout to 5s

// set custom user agent
// (this will result in the UA "foo/cool restclient-cpp/VERSION")

// enable following of redirects (default is off)
// and limit the number of redirects (default is -1, unlimited)
conn->FollowRedirects(true, 3);

// set headers
RestClient::HeaderFields headers;
headers["Accept"] = "application/json";

// append additional headers
conn->AppendHeader("X-MY-HEADER", "foo")

// if using a non-standard Certificate Authority (CA) trust file

RestClient::Response r = conn->get("/get")
RestClient::Response r = conn->head("/get")
RestClient::Response r = conn->del("/delete")
RestClient::Response r = conn->options("/options")

// set different content header for POST, PUT and PATCH
conn->AppendHeader("Content-Type", "application/json")
RestClient::Response r = conn->post("/post", "{\"foo\": \"bla\"}")
RestClient::Response r = conn->put("/put", "application/json", "{\"foo\": \"bla\"}")
RestClient::Response r = conn->patch("/patch", "text/plain", "foobar")

// deinit RestClient. After calling this you have to call RestClient::init()
// again before you can use it

The responses are again of type RestClient::Response and have three attributes:

RestClient::Response.code // HTTP response code
RestClient::Response.body // HTTP response body
RestClient::Response.headers // HTTP response headers

The connection object also provides a simple way to get some diagnostics and metrics information via conn->GetInfo(). The result is a RestClient::Connection::Info struct and looks like this:

typedef struct {
  std::string base_url;
  RestClients::HeaderFields headers;
  int timeout;
  struct {
    std::string username;
    std::string password;
  } basicAuth;

  std::string certPath;
  std::string certType;
  std::string keyPath;
  std::string keyPassword;
  std::string customUserAgent;
  std::string uriProxy;
  struct {
    // total time of the last request in seconds Total time of previous
    // transfer. See CURLINFO_TOTAL_TIME
    int totalTime;
    // time spent in DNS lookup in seconds Time from start until name
    // resolving completed. See CURLINFO_NAMELOOKUP_TIME
    int nameLookupTime;
    // time it took until Time from start until remote host or proxy
    // completed. See CURLINFO_CONNECT_TIME
    int connectTime;
    // Time from start until SSL/SSH handshake completed. See
    int appConnectTime;
    // Time from start until just before the transfer begins. See
    int preTransferTime;
    // Time from start until just when the first byte is received. See
    int startTransferTime;
    // Time taken for all redirect steps before the final transfer. See
    int redirectTime;
    // number of redirects followed. See CURLINFO_REDIRECT_COUNT
    int redirectCount;
  } lastRequest;
} Info;

Persistent connections/Keep-Alive

The connection object stores the curl easy handle in an instance variable and uses that for the lifetime of the object. This means curl will automatically reuse connections made with that handle.

Progress callback

Two wrapper functions are provided to setup the progress callback for uploads/downloads.

Calling conn->SetFileProgressCallback(callback) with a callback parameter matching the prototype int progress_callback(void *clientp, double dltotal, double dlnow, double ultotal, double ulnow) will setup the progress callback.

Calling conn->SetFileProgressCallbackData(data) is optional. This will set the data pointer which is the first parameter fed back to the progress callback - clientp. If this isn't set then clientp will default to the connection object conn.


Write callback

A write callback function can be provided for processing data as it's received from a GET call (for instance the Kubernetes Watch API).

Calling conn->SetWriteFunction(callback) with a function parameter matching the prototype size_t write_function(void *data, size_t size, size_t nmemb, void *userdata)int progress_callback(void *clientp, double dltotal, double dlnow, double ultotal, double ulnow) will setup the write function.

Here is an example of a write callback function, processing result data line by line.

auto writeCallback = [](void *data, size_t size, size_t nmemb, void *userdata) -> size_t
  size_t bytes = size * nmemb;
      // Add to the buffer
      auto res = reinterpret_cast<RestClient::Response *>(userdata);
      res->body.append(static_cast<char*>(data), bytes);
      // If the last character is not a new line, wait for the rest.
      if ('\n' != *(res->body.end() - 1))
          return bytes;
      // Process data one line at a time.
      std::stringstream stream(res->body);
      std::string line;
      while (std::getline(stream, line))
        // Do something with the line here...
      // Done processing the line
  catch(std::exception e)
      // Log caught exception here
      return 0;
  return bytes;

Error handling

When restclient-cpp encounters an error, generally the error (or "status") code is returned in the Response (see Response struct in restclient.h). This error code can be either an HTTP error code, or if a lower-level cURL error was encountered, it may be a CURLCode. Currently, libcurl only defines 92 error codes, which means there is no overlap between cURL error codes and HTTP response codes (which start at 1xx). However, if in the future, libcurl defines more than 99 error codes, meaning that cURL errors overlap with the HTTP 1xx class of responses, restclient-cpp will return a -1 if the CURLCode is 100 or higher. In this case, callers can use GetInfo().lastRequest.curlCode to inspect the actual cURL error.

Thread Safety

restclient-cpp leans heavily on libcurl as it aims to provide a thin wrapper around it. This means it adheres to the basic level of thread safety provided by libcurl. The RestClient::init() and RestClient::disable() methods basically correspond to curl_global_init and curl_global_cleanup and thus need to be called right at the beginning of your program and before shutdown respectively. These set up the environment and are not thread-safe. After that you can create connection objects in your threads. Do not share connection objects across threads as this would mean accessing curl handles from multiple threads at the same time which is not allowed.

The connection level method SetNoSignal can be set to skip all signal handling. This is important in multi-threaded applications as DNS resolution timeouts use signals. The signal handlers quite readily get executed on other threads. Note that with this option DNS resolution timeouts do not work. If you have crashes in your multi-threaded executable that appear to be in DNS resolution, this is probably why.

In order to provide an easy to use API, the simple usage via the static methods implicitly calls the curl global functions and is therefore also not thread-safe.

HTTPS User Certificate

Simple wrapper functions are provided to allow clients to authenticate using certificates. Under the hood these wrappers set cURL options, e.g. CURLOPT_SSLCERT, using curl_easy_setopt. Note: currently libcurl compiled with gnutls (e.g. libcurl4-gnutls-dev on ubuntu) is buggy in that it returns a wrong error code when these options are set to invalid values.


HTTP Proxy Tunneling Support

An HTTP Proxy can be set to use for the upcoming request. To specify a port number, append :[port] to the end of the host name. If not specified, libcurl will default to using port 1080 for proxies. The proxy string may be prefixed with http:// or https://. If no HTTP(S) scheme is specified, the address provided to libcurl will be prefixed with http:// to specify an HTTP proxy. A proxy host string can embedded user + password. The operation will be tunneled through the proxy as curl option CURLOPT_HTTPPROXYTUNNEL is enabled by default. A numerical IPv6 address must be written within [brackets].

/* or you can set it without the protocol scheme and
http:// will be prefixed by default */
/* the following request will be tunneled through the proxy */
RestClient::Response res = conn->get("/get");

Unix Socket Support

Note that the URL used with a unix socket has only ONE leading forward slash.

RestClient::Connection* conn = new RestClient::Connection("http:/v1.30");
RestClient::HeaderFields headers;
headers["Accept"] = "application/json; charset=UTF-8";
headers["Expect"] = "";
auto resp = conn->get("/images/json");



There are some packages available for Linux on packagecloud. And for OSX you can get it from the mrtazz/oss homebrew tap:

brew tap mrtazz/oss
brew install restclient-cpp

Otherwise you can do the regular autotools dance:

make install

Alternatively, you can build and install restclient-cpp using vcpkg dependency manager:

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./vcpkg integrate install
./vcpkg install restclient-cpp

The restclient-cpp port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please create an issue or pull request on the vcpkg repository.


All contributions are highly appreciated. This includes filing issues, updating documentation and writing code. Please take a look at the contributing guidelines before so your contribution can be merged as fast as possible.

  • Added a method to perform POST Form Upload

    Added a method to perform POST Form Upload

    Some REST platforms (e.g. Symphony) require a POST Form upload in some requests to send data to them. So I added code to perform post form upload.

    I created a helper object to wrap HTML form information. Then we pass it to postForm method to perform the upload.

    The unit test I wrote uses Henry's HTTP Post dumping server http://posttestserver.com/ The details of the upload of the dummy test file can be found under http://posttestserver.com/data (/[year]/[month]/[day]/restclientcpptests/)

    There's no memory leaks.

    opened by embeddedmz 30
  • Undefined reference to `RestClient::get(std::string const&)'

    Undefined reference to `RestClient::get(std::string const&)'


    So I installed all the files using the configure, make and make install commands. Now when I use the example I get the following error: Undefined reference to RestClient::get(std::string const&). Do you have any idea how to fix this?

    opened by Jorricks 22
  • Issue #21 - Memory leak

    Issue #21 - Memory leak

    This is my first contribution to an open source project and my first use of GitHub so if I did anything incorrectly, just delete this entire thing.

    If the remote server does not respond to the HTTP request, line 223 (for example) returns from the PUT function before doing the CURL cleanups on lines 229 thru 231. This causes a memory leak.

    I tested the following code change with the PUT function and it resolves the leak. I made changes in all functions that had similar code.

    if (res != CURLE_OK) { ret.body = "Failed to query."; ret.code = -1; //return ret; //Commented the return } else { //else added here long http_code = 0; curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &http_code); ret.code = static_cast(http_code); } ...Followed by CURL cleanup and return statement.

    Functions now have only one return statement.

    opened by watsocd 11
  • File streaming

    File streaming

    Main content of this PR is the possibility to download and upload data directly to / from files instead of keeping it in memory in the Response object. Additionally there is a possibility to install a progress callback to track the amount of data sent or received.

    I extended the error handling a bit as well. Before the change the Response.code contains either the HTTP response code, the value of 28 (in case of a timeout), or -1 in case of other errors. I changed it to contain either the HTTP code, or a negative value containing the curl error code.

    Detailed changes:

    • Support for streaming the request body from a file and the response body to a file - useful for uploads and downloads
    • Possibility to install a progress callback
    • Added C compiler flag to use C++11 (needed for progress callback which is a std::function)
    • Added possibility to set a debug proxy for inspecting request / response traffic
    • Extended error handling: The response code contains either the HTTP code, or a negative value containing the curl error code.
    • Unit tests for the above
    • Updated README.md
    opened by wroluk 10
  • write callback and termination API

    write callback and termination API


    1. Allow write callback. Application was to use it to leverage the Kubernetes watch API which maintains a long-running connection.
    2. API to terminate connection from another thread.
    3. Fix all the disabled/broken CI tests that block the merge.


    Not all of these might apply to your change but the more you are able to check the easier it will be to get your contribution merged.

    • [X] CI passes
    • [X] Description of proposed change
    • [X] Documentation (README, code doc blocks, etc) is updated
    • [X] Existing issue is referenced if there is one
      • #162 write callback support
      • #161 CI does not work locally
    • [X] Unit tests for the proposed change
    opened by edwinpjacques 7
  • Empty response, no connection

    Empty response, no connection


    I'm using a slightly modified version of the advanced example from the README and having issues getting off the ground. Specifically, the response object returned from conn -> post(...) comes back instantly with code 500 and an empty body. The server it's supposed to be talking to receives no requests.

    The code I'm using looks like this

    Proxy::Proxy(Proxy::Settings settings)
        // parse settings
    // requests are handled by a thread pool
        // translate end-user request for back-end server
        std::string workerAddress; // address to back-end server, no trailing slash
        std::string payload; // json string with escaped quotes
        std::unique_ptr<RestClient::Connection> conn(new RestClient::Connection(workerAddress));
        RestClient::HeaderFields headers;
        headers["Content-Type"] = "application/json";
        RestClient::Response r = conn->post("/", payload);
        // translate r back to what the end-user wants

    Environment and debugging details

    Thanks for any help in the right direction!

    opened by afiorillo 7
  • Added Cookie Feature. Now you can use Cookies with this  restClient.

    Added Cookie Feature. Now you can use Cookies with this restClient.

    With this simple expansion the Rest Client is able to use Cookies. It saves the cookies to a file 'cookie' and use it with every following request. This can be used for a simple authentification check, which should be part of a restfull service.

    opened by chfo 7
  • Debian package: undefined reference to `curl_easy_getinfo@CURL_OPENSSL_3'

    Debian package: undefined reference to `[email protected]_OPENSSL_3'

    It seems the shared library in the Debian buster package is built against libcurl3, which is not available in Debian buster.

    Source code

    #include <restclient-cpp/restclient.h>
    int main()
        RestClient::Response r = RestClient::get("https://example.com");

    Compile flags

    $ g++ --std=c++14 -lrestclient-cpp $(pkg-config --libs --cflags libcurl) -lpthread test.cpp

    Actual behaviour

    /usr/bin/ld: /tmp/ccSW6rEE.o: in function `main':
    test.cpp:(.text+0x41): undefined reference to `RestClient::get(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&)'
    /usr/bin/ld: /usr/lib/gcc/x86_64-linux-gnu/8/../../../../lib/librestclient-cpp.so: undefined reference to `[email protected]_OPENSSL_3'

    … and so on.

    ldd output

    $ ldd /usr/lib/librestclient-cpp.so
    /usr/lib/librestclient-cpp.so: /lib/x86_64-linux-gnu/libcurl.so.4: version `CURL_OPENSSL_3' not found (required by /usr/lib/librestclient-cpp.so)

    Environment and debugging details

    • compiler and version
      • g++ (Debian 8.3.0-6) 8.3.0
    • operating system
      • Debian 10 (buster)
    • version of restclient-cpp
      • 0.5.1-1
    • how did you install restclient-cpp? (via packages, git, tarball)
      • Debian package for buster amd64
    • libcurl version and compile flags
      • Debian package libcurl4, version 7.64.0-4
    • full error output of your build as an inline codeblock or gist
    /usr/bin/ld: /tmp/ccejRJkF.o: in function `main':
    test.cpp:(.text+0x41): undefined reference to `RestClient::get(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&)'
    /usr/bin/ld: /usr/lib/gcc/x86_64-linux-gnu/8/../../../../lib/librestclient-cpp.so: undefined reference to `[email protected]_OPENSSL_3'
    /usr/bin/ld: /usr/lib/gcc/x86_64-linux-gnu/8/../../../../lib/librestclient-cpp.so: undefined reference to `[email protected]_OPENSSL_3'
    /usr/bin/ld: /usr/lib/gcc/x86_64-linux-gnu/8/../../../../lib/librestclient-cpp.so: undefined reference to `[email protected]_OPENSSL_3'
    /usr/bin/ld: /usr/lib/gcc/x86_64-linux-gnu/8/../../../../lib/librestclient-cpp.so: undefined reference to `[email protected]_OPENSSL_3'
    /usr/bin/ld: /usr/lib/gcc/x86_64-linux-gnu/8/../../../../lib/librestclient-cpp.so: undefined reference to `[email protected]_OPENSSL_3'
    /usr/bin/ld: /usr/lib/gcc/x86_64-linux-gnu/8/../../../../lib/librestclient-cpp.so: undefined reference to `[email protected]_OPENSSL_3'
    /usr/bin/ld: /usr/lib/gcc/x86_64-linux-gnu/8/../../../../lib/librestclient-cpp.so: undefined reference to `[email protected]_OPENSSL_3'
    /usr/bin/ld: /usr/lib/gcc/x86_64-linux-gnu/8/../../../../lib/librestclient-cpp.so: undefined reference to `[email protected]_OPENSSL_3'
    /usr/bin/ld: /usr/lib/gcc/x86_64-linux-gnu/8/../../../../lib/librestclient-cpp.so: undefined reference to `[email protected]_OPENSSL_3'
    /usr/bin/ld: /usr/lib/gcc/x86_64-linux-gnu/8/../../../../lib/librestclient-cpp.so: undefined reference to `[email protected]_OPENSSL_3'
    /usr/bin/ld: /usr/lib/gcc/x86_64-linux-gnu/8/../../../../lib/librestclient-cpp.so: undefined reference to `[email protected]_OPENSSL_3'
    collect2: error: ld returned 1 exit status
    debian build issues 
    opened by tastytea 6
  • use lambda's over ptr_fun

    use lambda's over ptr_fun

    ptr_fun was deprecated in C++11, and removed in C++17. lambdas have also been around since C++11. so there should be no loss in supported targets, but also adds in support for C++17 and beyond.

    opened by Mythra 6
  • Compilation on Cygwin does not build shared libraries

    Compilation on Cygwin does not build shared libraries

    Attempting to compile the library on cygwin yields the libtool error:

    libtool: warning: undefined symbols not allowed in x86_64-unknown-cygwin shared
    libraries; building static only

    Indeed, attempting to compile a program with the library yields a slew of reference not found errors in the vein of:

    undefined reference to `RestClient::post(std::string const&, std::string const&, 
    std::string const&)'
    relocation truncated to fit: R_X86_64_PC32 against undefined symbol `RestClient::post(
    std::string const&, std::string const&, std::string const&)'
    collect2: error: ld returned 1 exit status
    help wanted windows 
    opened by instigatorofawe 6
  • bundle json-cpp with restclient

    bundle json-cpp with restclient

    most REST APIs are JSON based anways. So maybe it would make this a lot nicer to use if it came with an opinionated way of how JSON responses are parsed into objects. At least look into it.

    opened by mrtazz 6
Daniel Schauenberg
infra engineer. A Cheap Trick and a Cheesy One-Liner. git and a Makefile. Feminist.
Daniel Schauenberg
HTTP/HTTPS REST Client C Library

https_client HTTP/HTTPS REST Client C Library This library is a tiny https client library. it use only small memory(default read buffer size(H_READ_SI

HISONA 97 Jul 21, 2022
C++ Requests: Curl for People, a spiritual port of Python Requests

C++ Requests: Curl for People Announcements The cpr project has new maintainers: Fabian Sauter and Tim Stack. TLDR C++ Requests is a simple wrapper ar

Huu Nguyen 4.8k Aug 2, 2022
H2O - the optimized HTTP/1, HTTP/2, HTTP/3 server

H2O - an optimized HTTP server with support for HTTP/1.x, HTTP/2 and HTTP/3 (experimental) Copyright (c) 2014-2019 DeNA Co., Ltd., Kazuho Oku, Tatsuhi

H2O 10.1k Aug 4, 2022
C++ library for creating an embedded Rest HTTP server (and more)

The libhttpserver reference manual Tl;dr libhttpserver is a C++ library for building high performance RESTful web servers. libhttpserver is built upon

Sebastiano Merlino 667 Aug 3, 2022
Filter Garry'sMod built-in HTTP requests with a lua hook

Filter Garry'sMod built-in HTTP requests with a lua hook

Earu 3 Jul 28, 2022
The C++ REST SDK is a Microsoft project for cloud-based client-server communication in native code using a modern asynchronous C++ API design. This project aims to help C++ developers connect to and interact with services.

Welcome! The C++ REST SDK is a Microsoft project for cloud-based client-server communication in native code using a modern asynchronous C++ API design

Microsoft 7k Aug 6, 2022
Modern C++ REST Client library

Introduction to the restc-cpp C++ library The magic that takes the pain out of accessing JSON API's from C++ What it does: It formulates a HTTP reques

Jarle Aase 483 Jul 25, 2022
tiny HTTP parser written in C (used in HTTP::Parser::XS et al.)

PicoHTTPParser Copyright (c) 2009-2014 Kazuho Oku, Tokuhiro Matsuno, Daisuke Murase, Shigeo Mitsunari PicoHTTPParser is a tiny, primitive, fast HTTP r

H2O 1.5k Aug 6, 2022
A collection of C++ HTTP libraries including an easy to use HTTP server.

Proxygen: Facebook's C++ HTTP Libraries This project comprises the core C++ HTTP abstractions used at Facebook. Internally, it is used as the basis fo

Facebook 7.6k Jul 27, 2022
Pushpin is a reverse proxy server written in C++ that makes it easy to implement WebSocket, HTTP streaming, and HTTP long-polling services.

Pushpin is a reverse proxy server written in C++ that makes it easy to implement WebSocket, HTTP streaming, and HTTP long-polling services. The project is unique among realtime push solutions in that it is designed to address the needs of API creators. Pushpin is transparent to clients and integrates easily into an API stack.

Fanout 3.1k Aug 4, 2022
cuehttp is a modern c++ middleware framework for http(http/https)/websocket(ws/wss).

cuehttp 简介 cuehttp是一个使用Modern C++(C++17)编写的跨平台、高性能、易用的HTTP/WebSocket框架。基于中间件模式可以方便、高效、优雅的增加功能。cuehttp基于boost.asio开发,使用picohttpparser进行HTTP协议解析。内部依赖了nl

xcyl 26 Jul 21, 2022
Gromox - Groupware server backend with MAPI/HTTP, RPC/HTTP, IMAP, POP3 and PHP-MAPI support for grommunio

Gromox is the central groupware server component of grommunio. It is capable of serving as a replacement for Microsoft Exchange and compatibles. Conne

grommunio 120 Jul 2, 2022
A REST API in C, yeah, C...

A REST API that fetches custom data from École 42 users, written in C. (Challenge from 42Labs) Constructed with: Mongoose Mjson Org-mode MongoDB Atlas

Henrique Rocha 3 Jun 14, 2022
Various utilities such as WebServer, JSON, WebSocket server, REST framework

DumaisLib This is a library containing several utilities for some projects of Patrick Dumais. Previously, the libraries were all individual but it bec

Patrick Dumais 25 Feb 22, 2022
C++ Web Framework REST API

✨ wfrest: C++ Web Framework REST API Fast, efficient, and easiest c++ async micro web framework based on C++ Workflow. ?? Contents wfrest: C++ Web Fra

null 411 Jul 30, 2022
A C library for asynchronous DNS requests

c-ares This is c-ares, an asynchronous resolver library. It is intended for applications which need to perform DNS queries without blocking, or need t

c-ares 1.5k Aug 5, 2022
Application that sends custom requests to League of Legends LCU api

More screenshots For fun project made in the span of 2 nights back in February 2021, which I'm now updating Technologies used No external libraries, o

null 121 Aug 6, 2022
requests-like networking library using boost for C++

cq == C++ Requests cq == C++ Requests is a "Python Requests"-like C++ header-only library for sending HTTP requests. The library is inspired a lot by

null 11 Dec 15, 2021
traces tcp requests in kernel. allow to set up IPs to filter dynamically using bpf-map.

ttcp cilium/ebpf/examples/tcprtt에다가 BPF_MAP_TYPE_HASH를 추가해서 srcAddr을 필터링하도록 수정함. 어플리케이션에는 Http API를 추가해서 필터링할 IP를 추가, 삭제, 조회할 수 있도록 함. Getting Startd

null 8 May 20, 2022