From 52d1e3bb66bae5ea4053e346862afe5914a43294 Mon Sep 17 00:00:00 2001
From: Leonid Stryzhevskyi <lganzzzo@gmail.com>
Date: Sun, 14 Oct 2018 12:49:59 +0300
Subject: [PATCH] Update README.md

---
 README.md | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 128 insertions(+)

diff --git a/README.md b/README.md
index dedc340f..c3265c5c 100644
--- a/README.md
+++ b/README.md
@@ -21,6 +21,134 @@ Organic. Pure C++.
 - Simple Test framework
 - HTTP_1.1 (2.0 comes shortly)
 
+## Simple API overview
+"Simple API" refers to as API used together with ```oatpp::web::server::HttpConnectionHandler``` utilizing multithreading plus blocking-IO approach. 
+
+### Create Endpoint
+
+```c++
+ENDPOINT("GET", "demo/api/hello", hello) {
+  return createResponse(Status::CODE_200, "Hello World!");
+}
+```
+
+### Pass parameters to endpoint
+
+```c++
+ENDPOINT("GET", "demo/api/param/{param}", getWithParams,
+         PATH(String, param)) {
+  return createResponse(Status::CODE_200, "param=" + param);
+}
+```
+
+### Return JSON
+
+```c++
+ENDPOINT("GET", "demo/api/json", getJson) {
+  auto dto = MyDto::createShared();
+  dto->statusCode = 200;
+  dto->message = "Hello json";
+  return createDtoResponse(Status::CODE_200, dto);
+}
+```
+**Output:**
+```
+{"message": "Hello json", "statusCode": 200}
+```
+
+### Post JSON body
+
+```c++
+ENDPOINT("POST", "demo/api/json", postJson,
+         BODY_DTO(MyDto::ObjectWrapper, dto)) {
+  auto dtoMessage = dto->message;
+  return createResponse(Status::CODE_200, "dtoMessage: " + dtoMessage);
+}
+```
+
+**Terminal:**
+
+```
+$ curl -X POST "localhost:8001/demo/api/json" -d '{"message": "hello json post"}'
+dtoMessage: hello json post
+```
+
+## Async API overview
+"Async API" refers to as API used together with ```oatpp::web::server::AsyncHttpConnectionHandler``` utilizing oatpp-coroutines plus non-blocking-IO approach. 
+
+### Create Endpoint Async
+```c++
+ENDPOINT_ASYNC("GET", "demo/api_async/hello", HelloAsync) {
+
+  ENDPOINT_ASYNC_INIT(HelloAsync)
+
+  Action act() override {
+    return _return(controller->createResponse(Status::CODE_200, "Hello World Async API!"));
+  }
+
+};
+```
+
+### Pass parameters to endpoint Async
+```c++
+ENDPOINT_ASYNC("GET", "demo/api_async/param/{param}", GetWithParamsAsync) {
+
+  ENDPOINT_ASYNC_INIT(GetWithParamsAsync)
+
+  Action act() override {
+    auto param = request->getPathVariable("param");
+    return _return(controller->createResponse(Status::CODE_200, "param=" + param));
+  }
+
+};
+```
+
+### Return JSON Async
+```c++
+ENDPOINT_ASYNC("GET", "demo/api_async/json", GetJSONAsync) {
+
+  ENDPOINT_ASYNC_INIT(GetJSONAsync)
+
+  Action act() override {
+    auto dto = MyDto::createShared();
+    dto->statusCode = 200;
+    dto->message = "Hello json";
+    return _return(controller->createDtoResponse(Status::CODE_200, dto));
+  }
+
+};
+```
+
+**Output:**
+```
+{"message": "Hello json", "statusCode": 200}
+```
+
+### Post JSON body Async
+```c++
+ENDPOINT_ASYNC("POST", "demo/api_async/json", PostJSONAsync) {
+
+  ENDPOINT_ASYNC_INIT(PostJSONAsync)
+
+  Action act() override {
+    return request->readBodyToDtoAsync<MyDto>(this,
+                                              &PostJSONAsync::onBodyObtained,
+                                              controller->getDefaultObjectMapper());
+  }
+
+  Action onBodyObtained(const MyDto::ObjectWrapper& dto) {
+    return _return(controller->createResponse(Status::CODE_200, "dtoMessage: " + dto->message));
+  }
+
+};
+```
+
+**Terminal:**
+```
+$ curl -X POST "localhost:8001/demo/api_async/json" -d '{"message": "hello json post"}'
+dtoMessage: hello json post
+```
+
 ## How to start
 
 Grab any project from [examples](https://github.com/oatpp/oatpp-examples), and follow README