README.md
1# C++ Requests: Curl for People <img align="right" height="40" src="http://i.imgur.com/d9Xtyts.png">
2
3[](https://docs.libcpr.org/)
4
5[](https://gitter.im/libcpr/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
6
7## Announcements
8
9* Like you probably have noticed, `cpr` moved to a new home from https://github.com/whoshuu/cpr to https://github.com/libcpr/cpr. Read more [here](https://github.com/libcpr/cpr/issues/636).
10* This project is being maintained by [Fabian Sauter](https://github.com/com8) and [Kilian Traub](https://github.com/KingKili).
11* For quick help, and discussion libcpr also offer a [gitter](https://gitter.im/libcpr/community?utm_source=share-link&utm_medium=link&utm_campaign=share-link) chat.
12
13## TLDR
14
15C++ Requests is a simple wrapper around [libcurl](http://curl.haxx.se/libcurl) inspired by the excellent [Python Requests](https://github.com/kennethreitz/requests) project.
16
17Despite its name, libcurl's easy interface is anything but, and making mistakes misusing it is a common source of error and frustration. Using the more expressive language facilities of C++11, this library captures the essence of making network calls into a few concise idioms.
18
19Here's a quick GET request:
20
21```c++
22#include <cpr/cpr.h>
23
24int main(int argc, char** argv) {
25 cpr::Response r = cpr::Get(cpr::Url{"https://api.github.com/repos/whoshuu/cpr/contributors"},
26 cpr::Authentication{"user", "pass"},
27 cpr::Parameters{{"anon", "true"}, {"key", "value"}});
28 r.status_code; // 200
29 r.header["content-type"]; // application/json; charset=utf-8
30 r.text; // JSON text string
31}
32```
33
34And here's [less functional, more complicated code, without cpr](https://gist.github.com/whoshuu/2dc858b8730079602044).
35
36## Documentation
37
38[](https://docs.libcpr.org/)
39You can find the latest documentation [here](https://docs.libcpr.org/). It's a work in progress, but it should give you a better idea of how to use the library than the [tests](https://github.com/libcpr/cpr/tree/master/test) currently do.
40
41## Features
42
43C++ Requests currently supports:
44
45* Custom headers
46* Url encoded parameters
47* Url encoded POST values
48* Multipart form POST upload
49* File POST upload
50* Basic authentication
51* Bearer authentication
52* Digest authentication
53* NTLM authentication
54* Connection and request timeout specification
55* Timeout for low speed connection
56* Asynchronous requests
57* :cookie: support!
58* Proxy support
59* Callback interfaces
60* PUT methods
61* DELETE methods
62* HEAD methods
63* OPTIONS methods
64* PATCH methods
65* Thread Safe access to [libCurl](https://curl.haxx.se/libcurl/c/threadsafe.html)
66* OpenSSL and WinSSL support for HTTPS requests
67
68## Planned
69
70For a quick overview about the planed features, have a look at the next [Milestones](https://github.com/libcpr/cpr/milestones).
71
72## Usage
73
74### CMake
75
76If you already have a CMake project you need to integrate C++ Requests with, the primary way is to use `fetch_content`.
77Add the following to your `CMakeLists.txt`.
78
79
80```cmake
81include(FetchContent)
82FetchContent_Declare(cpr GIT_REPOSITORY https://github.com/libcpr/cpr.git GIT_TAG 67e12da316754ff3c6c91b50aafb2658438f3c1e) # the commit hash for 1.7.0
83FetchContent_MakeAvailable(cpr)
84```
85
86This will produce the target `cpr::cpr` which you can link against the typical way:
87
88```cmake
89target_link_libraries(your_target_name PRIVATE cpr::cpr)
90```
91
92That should do it!
93There's no need to handle `libcurl` yourself. All dependencies are taken care of for you.
94
95### Packages for Linux Distributions
96
97Alternatively, you may install a package specific to your Linux distribution. Since so few distributions currently have a package for cpr, most users will not be able to run your program with this approach.
98
99Currently, we are aware of packages for the following distributions:
100
101* [Arch Linux (AUR)](https://aur.archlinux.org/packages/cpr)
102
103If there's no package for your distribution, try making one! If you do, and it is added to your distribution's repositories, please submit a pull request to add it to the list above. However, please only do this if you plan to actively maintain the package.
104
105## Requirements
106
107The only explicit requirements are:
108
109* a `C++11` compatible compiler such as Clang or GCC. The minimum required version of GCC is unknown, so if anyone has trouble building this library with a specific version of GCC, do let me know
110* If you would like to perform https requests `OpenSSL` and its development libraries are required.
111
112## Building cpr - Using vcpkg
113
114You can download and install cpr using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:
115```Bash
116git clone https://github.com/Microsoft/vcpkg.git
117cd vcpkg
118./bootstrap-vcpkg.sh
119./vcpkg integrate install
120./vcpkg install cpr
121```
122The `cpr` 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](https://github.com/Microsoft/vcpkg) on the vcpkg repository.
123
124## Building cpr - Using Conan
125
126You can download and install `cpr` using the [Conan](https://conan.io/) package manager. Setup your CMakeLists.txt (see [Conan documentation](https://docs.conan.io/en/latest/integrations/build_system.html) on how to use MSBuild, Meson and others) like this:
127
128```CMake
129project(myproject CXX)
130
131add_executable(${PROJECT_NAME} main.cpp)
132
133include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake) # Include Conan-generated file
134conan_basic_setup(TARGETS) # Introduce Conan-generated targets
135
136# depending on your conan and cmake configuration, you may need to set the used ABI:
137# add_definitions(-D_GLIBCXX_USE_CXX11_ABI=0) # uncomment/add this line if the build fails or you get a runtime error
138
139target_link_libraries(${PROJECT_NAME} CONAN_PKG::cpr)
140```
141Create `conanfile.txt` in your source dir:
142```
143[requires]
144cpr/1.6.2
145
146[generators]
147cmake
148```
149Install and run Conan, then build your project as always:
150
151```Bash
152pip install conan
153mkdir build
154cd build
155conan install ../ --build=missing
156cmake ../
157cmake --build .
158```
159The `cpr` package in Conan is kept up to date by Conan contributors. If the version is out of date, please [create an issue or pull request](https://github.com/conan-io/conan-center-index) on the `conan-center-index` repository.
160
){kind=link}
){kind=link}