Restclient Cpp

C++ client for making HTTP/REST requests
Alternatives To Restclient Cpp
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
Hoppscotch51,662111 hours ago1March 22, 2022144mitTypeScript
👽 Open source API development ecosystem -
Httpie27,8561,645426 days ago55May 06, 2022146bsd-3-clausePython
🥧 HTTPie for Terminal — modern, user-friendly command-line HTTP client for the API era. JSON support, colors, sessions, downloads, plugins & more.
42 days ago37July 12, 2022207mitHaskell
REST API for any Postgres database
Okhttp Okgo10,444
9 months ago461apache-2.0Java
OkGo - 3.0 震撼来袭,该库是基于 Http 协议,封装了 OkHttp 的网络请求框架,比 Retrofit 更简单易用,支持 RxJava,RxJava2,支持自定义缓存,支持批量断点下载管理和批量上传管理功能
Falcon9,05935 days ago4March 25, 2022162apache-2.0Python
The no-magic web data plane API and microservices framework for Python developers, with a focus on reliability, correctness, and performance at scale.
Cowboy6,9289,060286a month ago23May 12, 2021106iscErlang
Small, fast, modern HTTP server for Erlang/OTP.
Rest Assured6,3497,364395a month ago29September 09, 2022503apache-2.0Java
Java DSL for easy testing of REST services
Wiremock5,5671,62675213 hours ago104September 10, 2020326apache-2.0Java
A tool for mocking HTTP services
Rest Client5,17552,4724,2027 months ago65August 22, 2019146mitRuby
Simple HTTP and REST client for Ruby, inspired by microframework syntax for specifying actions.
Restful Api Design References4,823
2 years ago2mit
RESTful API 设计参考文献列表,可帮助你更加彻底的了解REST风格的接口设计。
Alternatives To Restclient Cpp
Select To Compare

Alternative Project Comparisons

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("")
RestClient::Response r = RestClient::post("", "application/json", "{\"foo\": \"bla\"}")
RestClient::Response r = RestClient::put("", "application/json", "{\"foo\": \"bla\"}")
RestClient::Response r = RestClient::patch("", "application/json", "{\"foo\": \"bla\"}")
RestClient::Response r = RestClient::del("")
RestClient::Response r = RestClient::head("")
RestClient::Response r = RestClient::options("")

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("");

// 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
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.

Popular Http Projects
Popular Rest Projects
Popular Networking Categories
Related Searches

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.
C Plus Plus
Http Client
Rest Client