git.sur5r.net Git - minitube/blob - lib/http/README.md

   1 # A wrapper for the Qt Network Access API
   2
   3 This is just a wrapper around Qt's QNetworkAccessManager and friends. I use it in my apps at https://flavio.tordini.org . It has a simpler, higher-level API and some functionality not found in Qt:
   4
   5 - Throttling (as required by many web APIs nowadays)
   6 - Automatic retries
   7 - User agent and request header defaults
   8 - Partial requests
   9 - Easier POST requests
  10 - Read timeouts (don't let your requests get stuck forever). (now supported by Qt >= 5.15)
  11 - Redirection support (now supported by Qt >= 5.6)
  12
  13 ## Design
  14
  15 This library uses the [Decorator design pattern](https://en.wikipedia.org/wiki/Decorator_pattern) to modularize features and make it easy to add them and use them as needed. The main class is [Http](https://github.com/flaviotordini/http/blob/master/src/http.h), which implements the base features of a HTTP client. More specialized classes are:
  16
  17 - [CachedHttp](https://github.com/flaviotordini/http/blob/master/src/cachedhttp.h), a simple disk-based cache
  18 - [ThrottledHttp](https://github.com/flaviotordini/http/blob/master/src/throttledhttp.h), implements request throttling (aka limiting)
  19
  20 The constructor of these classes takes another Http instance for which they will act as a proxy. (See examples below). Following this design you can create your own Http subclass. For example, a different caching mechanism, an event dispatcher, custom request logging, etc.
  21
  22
  23 ## Build Instructions
  24 In order to build this library you can use either `qmake` or `cmake`.
  25
  26 ### qmake
  27 ```
  28 mkdir build
  29 cd build
  30 qmake ..
  31 make
  32 ```
  33
  34 ### CMake
  35 ```
  36 mkdir build
  37 cd build
  38 cmake ..
  39 make
  40 ```
  41
  42 ## Integration
  43
  44 You can use this library as a git submodule. For example, add it to your project inside a lib subdirectory:
  45
  46 ```
  47 git submodule add -b master https://github.com/flaviotordini/http lib/http
  48 ```
  49
  50 Then you can update your git submodules like this:
  51
  52 ```
  53 git submodule update --init --recursive --remote
  54 ```
  55
  56 To integrate the library in your qmake based project just add this to your .pro file:
  57
  58 ```
  59 include(lib/http/http.pri)
  60 ```
  61
  62 qmake builds all object files in the same directory. In order to avoid filename clashes use:
  63
  64 ```
  65 CONFIG += object_parallel_to_source
  66 ```
  67
  68 If you are using CMake you can integrate the library by adding the following lines to your CMakeLists.txt:
  69
  70 ```
  71 add_subdirectory(lib/http)
  72 ...
  73 target_link_library(your_super_cool_project <other libraries> http)
  74 ```
  75 or if you have installed http you can find it via:
  76
  77 ```
  78 find_library(http REQUIRED)
  79 ...
  80 target_link_library(your_super_cool_project <other libraries> http)
  81 ```
  82
  83
  84 ## Examples
  85
  86 A basic C++14 example:
  87
  88 ```
  89 #include "http.h"
  90
  91 auto reply = Http::instance().get("https://google.com/");
  92 connect(reply, &HttpReply::finished, this, [](auto &reply) {
  93     if (reply.isSuccessful()) {
  94         qDebug() << "Feel the bytes!" << reply.body();
  95     } else {
  96         qDebug() << "Something's wrong here" << reply.statusCode() << reply.reasonPhrase();
  97     }
  98 });
  99 ```
 100
 101 This is a real-world example of building a Http object with more complex features. It throttles requests, uses a custom user agent and caches results:
 102
 103 ```
 104 #include "http.h"
 105 #include "cachedhttp.h"
 106 #include "throttledhttp.h"
 107
 108 Http &myHttp() {
 109     static Http *http = [] {
 110         Http *http = new Http;
 111         http->addRequestHeader("User-Agent", userAgent());
 112
 113         ThrottledHttp *throttledHttp = new ThrottledHttp(*http);
 114         throttledHttp->setMilliseconds(1000);
 115
 116         CachedHttp *cachedHttp = new CachedHttp(*throttledHttp, "mycache");
 117         cachedHttp->setMaxSeconds(86400 * 30);
 118
 119         return cachedHttp;
 120     }();
 121     return *http;
 122 }
 123 ```
 124
 125 If the full power (and complexity) of QNetworkReply is needed you can always fallback to it:
 126
 127 ```
 128 #include "http.h"
 129
 130 HttpRequest req;
 131 req.url = "https://flavio.tordini.org/";
 132 QNetworkReply *reply = Http::instance().networkReply(req);
 133 // Use QNetworkReply as needed...
 134 ```
 135
 136 Note that features like redirection, retries and read timeouts won't work in this mode.
 137
 138 ## License
 139
 140 You can use this library under the MIT license and at your own risk. If you do, you're welcome contributing your changes and fixes.