From 8541ea4b16df772eb44c474b978a621697abddd8 Mon Sep 17 00:00:00 2001
From: Chunting Gu <chunting.gu@outlook.com>
Date: Fri, 9 Aug 2019 17:33:25 +0800
Subject: [PATCH] Add more examples for Client API.

---
 README.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 71 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 604d874..d3d0ec8 100644
--- a/README.md
+++ b/README.md
@@ -25,9 +25,10 @@ Git repo: https://github.com/sprinfall/webcc. Please check this one instead of t
 - No memory leak detected by [VLD](https://kinddragon.github.io/vld/)
 - etc.
 
-## Client API Examples
+## Client API
+
+Let's start from a complete client example:
 
-A complete client example: 
 ```cpp
 #include <iostream>
 
@@ -35,11 +36,11 @@ A complete client example:
 #include "webcc/logger.h"
 
 int main() {
-  // Configure logger.
+  // Configure logger to print only to console.
   WEBCC_LOG_INIT("", webcc::LOG_CONSOLE);
   
   // Session provides convenient request APIs, stores request configurations
-  // and manages persistent connenction.
+  // and manages persistent connenctions.
   webcc::ClientSession session;
 
   // Catch exceptions for error handling.
@@ -51,7 +52,7 @@ int main() {
     std::cout << r->data() << std::endl;
 
   } catch (const webcc::Error& error) {
-    std::cout << error << std::endl;
+    std::cerr << error << std::endl;
   }
 
   return 0;
@@ -59,12 +60,12 @@ int main() {
 ```
 
 The `Get()` method is nothing but a shortcut of `Request()`. Using `Request()` directly is more complicated:
+
 ```cpp
-auto r = session.Request(webcc::RequestBuilder{}.
-                         Get("http://httpbin.org/get")
-                         ());
+auto r = session.Request(webcc::RequestBuilder{}.Get("http://httpbin.org/get")());
 ```
-As you can see, a helper class named `RequestBuilder` is used to chain the parameters and finally build (don't miss the `()` operator) a request object.
+
+As you can see, a helper class named `RequestBuilder` is used to chain the parameters and finally build a request object. Please pay attention to the `()` operator.
 
 Both the shortcut and `Request()` accept URL query parameters:
 
@@ -80,6 +81,7 @@ session.Request(webcc::RequestBuilder{}.
 ```
 
 Adding additional headers is also easy:
+
 ```cpp
 session.Get("http://httpbin.org/get",
             {"key1", "value1", "key2", "value2"},
@@ -94,18 +96,76 @@ session.Request(webcc::RequestBuilder{}.
 ```
 
 Accessing HTTPS has no difference from HTTP:
+
 ```cpp
 session.Get("https://httpbin.org/get");
 ```
+
 *NOTE: The HTTPS/SSL support requires the build option `WEBCC_ENABLE_SSL` to be enabled.*
 
 Listing GitHub public events is not a big deal:
+
 ```cpp
 auto r = session.Get("https://api.github.com/events");
 ```
-You can then parse `r->data()` to JSON object with your favorite JSON library. My choice for the examples is [jsoncpp](https://github.com/open-source-parsers/jsoncpp). But the library itself doesn't understand JSON nor require one. It's up to you to choose the most appropriate JSON library.
 
-## Server API Examples
+You can then parse `r->data()` to JSON object with your favorite JSON library. My choice for the examples is [jsoncpp](https://github.com/open-source-parsers/jsoncpp). But Webcc itself doesn't understand JSON nor require one. It's up to you to choose the most appropriate JSON library.
+
+The shortcuts (`Get()`, `Post()`, etc.) are easier to use but `RequestBuilder` is more powerful. It provides a lot of functions for you to customize the request. Let's see more examples.
+
+In order to list the followers of an authorized GitHub user, you need either **Basic Authorization**:
+
+```cpp
+session.Request(webcc::RequestBuilder{}.
+                Get("https://api.github.com/user/followers").
+                AuthBasic(login, password)  // Should be replaced by real login and password
+                ());
+```
+
+Or **Token Authorization**:
+
+```cpp
+session.Request(webcc::RequestBuilder{}.
+                Get("https://api.github.com/user/followers").
+                AuthToken(token)  // Should be replaced by a valid token
+                ());
+```
+
+Though **Keep-Alive** (i.e., persistent connection) is a good feature and enabled by default, you can turn it off:
+
+```cpp
+auto r = session.Request(webcc::RequestBuilder{}.
+                         Get("http://httpbin.org/get").
+                         KeepAlive(false)  // No Keep-Alive
+                         ());
+```
+
+The API for other HTTP requests is no different from GET.
+
+POST request needs a body which is normally a JSON string for REST API. Let's post a small UTF-8 encoded JSON string:
+
+```cpp
+session.Request(webcc::RequestBuilder{}.
+                Post("http://httpbin.org/post").
+                Body("{'name'='Adam', 'age'=20}").
+                Json().Utf8()
+                ());
+```
+
+Webcc has the ability to stream large response data to a file. This is especially useful when downloading files.
+
+```cpp
+auto r = session.Request(webcc::RequestBuilder{}.
+                         Get("http://httpbin.org/image/jpeg")(),
+                         true);  // !!!
+
+// Move the streamed file to your destination.
+file_body->Move("./wolf.jpeg");
+```
+
+Please check the [examples](https://github.com/sprinfall/webcc/tree/master/examples/) for more information. 
+
+## Server API
 
 ### Hello, World!