|
1 | 1 | # libcpp-http-client |
2 | | -Modern non-blocking exception free HTTP Client library for C++ (17+) |
| 2 | +Modern, non-blocking and exception free, header-only HTTP Client library for C++ (17+) |
3 | 3 |
|
4 | 4 | [](https://github.com/lk-libs/libcpp-http-client/actions/workflows/linux.yml) |
5 | 5 | [](https://github.com/lk-libs/libcpp-http-client/actions/workflows/windows.yml) |
| 6 | + |
| 7 | + |
| 8 | +> [!NOTE] |
| 9 | +> Please read this document before using the library. I know you don't have time, but reading this document will save you time. What I call a document is just this file. Trial and error will cost you more time. |
| 10 | +
|
| 11 | +# Table of Contents |
| 12 | +* [How to add it to my project](#how-to-add-it-to-my-project) |
| 13 | +* [How to use? (Simplest way)](#how-to-use-simplest-way) |
| 14 | +* [What does exception free mean?](#what-does-exception-free-mean) |
| 15 | +* [What does non-blocking mean?](#what-does-non-blocking-mean) |
| 16 | +* [What about binary data?](#what-about-binary-data) |
| 17 | +* [Sending Custom HTTP Headers](#sending-custom-http-headers) |
| 18 | +* [POST request with form data](#post-request-with-form-data) |
| 19 | +* [POST request with JSON data](#post-request-with-json-data) |
| 20 | +* [What about others? (PUT, DELETE, PATCH)](#what-about-others-put-delete-patch) |
| 21 | +* [License](#license) |
| 22 | +* [Contact](#contact) |
| 23 | + |
| 24 | + |
| 25 | +## How to add it to my project? |
| 26 | + |
| 27 | +This is a header only library. So actually, all you need is to add the libcpp-http-client.hpp file to your project and start using it with #include. |
| 28 | + |
| 29 | +But this library is a kind of Curl wrapper that uses Curl under the hood. So, you need to add Curl to your project before to use it. |
| 30 | + |
| 31 | +You can find usage examples in the examples folder. You can also find a sample CMakeLists.txt file content below. |
| 32 | + |
| 33 | + |
| 34 | +```cmake |
| 35 | +cmake_minimum_required(VERSION 3.14) |
| 36 | +
|
| 37 | +project(myProject) |
| 38 | +
|
| 39 | +add_executable(myProject main.cpp) |
| 40 | +
|
| 41 | +find_package(CURL CONFIG REQUIRED) |
| 42 | +
|
| 43 | +target_link_libraries(myProject PRIVATE libcpp-http-client CURL::libcurl) |
| 44 | +
|
| 45 | +``` |
| 46 | + |
| 47 | + |
| 48 | +## How to use? (Simplest way) |
| 49 | + |
| 50 | +Below you can see the simplest use case sending QueryString parameters to an API via HTTP GET. |
| 51 | + |
| 52 | +> [!TIP] |
| 53 | +> Please do not use it this way, if more than one call will be made . You do not use the non-blocking feature in this way. |
| 54 | +
|
| 55 | + |
| 56 | +```cpp |
| 57 | +#include <fstream> |
| 58 | +#include "libcpp-http-client.hpp" |
| 59 | + |
| 60 | +using namespace lklibs; |
| 61 | + |
| 62 | +int main() { |
| 63 | + |
| 64 | + // The simplest but slowest method if multiple calls will be made |
| 65 | + auto response = HttpClient::getRequest("https://api.myproject.com?param1=7¶m2=test").get(); |
| 66 | + |
| 67 | + std::cout << "Succeed: " << response.succeed << std::endl; |
| 68 | + std::cout << "Http Status Code: " << response.statusCode << std::endl; |
| 69 | + std::cout << "Data: " << response.textData << std::endl; |
| 70 | + |
| 71 | + return 0; |
| 72 | +} |
| 73 | +``` |
| 74 | + |
| 75 | +## What does exception free mean? |
| 76 | + |
| 77 | +Exception Free means that no exception will be thrown for any call you make to this library. If the URL cannot be found, there is a timeout, there is an authorization problem or another error occurs on the server, the bool typed "succeed" field of the response is returned as false. In addition, the HTTP Status Code value returned from the server is returned in the int typed "statusCode" field and possibly additional error information that may be returned from the server is returned in the string typed "errorMessage" field. |
| 78 | + |
| 79 | +You can see an example use case below... |
| 80 | + |
| 81 | +```cpp |
| 82 | +#include <fstream> |
| 83 | +#include "libcpp-http-client.hpp" |
| 84 | + |
| 85 | +using namespace lklibs; |
| 86 | + |
| 87 | +int main() { |
| 88 | + |
| 89 | + auto response = HttpClient::getRequest("https://www.myinvalidurl.com").get(); |
| 90 | + |
| 91 | + // Instead of throwing an exception, the succeed field of the response object is set to false |
| 92 | + std::cout << "Succeed: " << response.succeed << std::endl; |
| 93 | + |
| 94 | + // And the http status code is set to the statusCode field |
| 95 | + std::cout << "Http Status Code: " << response.statusCode << std::endl; |
| 96 | + |
| 97 | + // Also if any error message is available, it is set to the errorMessage field |
| 98 | + std::cout << "Error Message: " << response.errorMessage << std::endl; |
| 99 | + |
| 100 | + return 0; |
| 101 | +} |
| 102 | +``` |
| 103 | + |
| 104 | +## What does non-blocking mean? |
| 105 | + |
| 106 | +## What about binary data? |
| 107 | + |
| 108 | +## Sending Custom HTTP Headers |
| 109 | + |
| 110 | +## POST request with form data |
| 111 | + |
| 112 | +## POST request with JSON data |
| 113 | + |
| 114 | +## What about others? (PUT, DELETE, PATCH) |
| 115 | + |
| 116 | +## License |
| 117 | + |
| 118 | +## Contact |
0 commit comments