sync vs async note

Author: winrid

README.md

@@ -106,6 +106,97 @@ int main() {
 2. **401 "missing-api-key" error**: Make sure you call `config->setApiKey(utility::conversions::to_string_t("api_key"), utility::conversions::to_string_t("YOUR_KEY"))` before creating the DefaultAPI instance.
 3. **Wrong API class**: Use `DefaultAPI` for server-side authenticated requests, `PublicAPI` for client-side/public requests.
 
+## Making API Calls: Synchronous vs Asynchronous
+
+All API methods in this SDK return `pplx::task<std::shared_ptr<ResponseType>>` from the C++ REST SDK. This gives you flexibility in how you handle API responses.
+
+### Synchronous Calls with `.get()`
+
+Use `.get()` to block the calling thread until the request completes and retrieve the result synchronously:
+
+```cpp
+auto config = std::make_shared<org::openapitools::client::api::ApiConfiguration>();
+config->setBaseUrl(utility::conversions::to_string_t("https://fastcomments.com"));
+config->setApiKey(utility::conversions::to_string_t("api_key"),
+                  utility::conversions::to_string_t("YOUR_API_KEY"));
+
+auto apiClient = std::make_shared<org::openapitools::client::api::ApiClient>(config);
+org::openapitools::client::api::DefaultApi api(apiClient);
+
+// Call .get() to block and get the result synchronously
+auto response = api.getComments(
+    utility::conversions::to_string_t("your-tenant-id"),
+    boost::none,  // page
+    boost::none,  // limit
+    boost::none,  // skip
+    boost::none,  // asTree
+    boost::none,  // skipChildren
+    boost::none,  // limitChildren
+    boost::none,  // maxTreeDepth
+    utility::conversions::to_string_t("your-url-id"),  // urlId
+    boost::none,  // userId
+    boost::none,  // anonUserId
+    boost::none,  // contextUserId
+    boost::none,  // hashTag
+    boost::none,  // parentId
+    boost::none   // direction
+).get();  // Blocks until the HTTP request completes
+
+if (response && response->comments) {
+    std::cout << "Found " << response->comments->size() << " comments" << std::endl;
+}
+```
+
+### Asynchronous Calls with `.then()`
+
+Use `.then()` for non-blocking asynchronous execution with callbacks:
+
+```cpp
+auto config = std::make_shared<org::openapitools::client::api::ApiConfiguration>();
+config->setBaseUrl(utility::conversions::to_string_t("https://fastcomments.com"));
+config->setApiKey(utility::conversions::to_string_t("api_key"),
+                  utility::conversions::to_string_t("YOUR_API_KEY"));
+
+auto apiClient = std::make_shared<org::openapitools::client::api::ApiClient>(config);
+org::openapitools::client::api::DefaultApi api(apiClient);
+
+// Use .then() for asynchronous callback-based execution
+api.getComments(
+    utility::conversions::to_string_t("your-tenant-id"),
+    boost::none, boost::none, boost::none, boost::none, boost::none,
+    boost::none, boost::none,
+    utility::conversions::to_string_t("your-url-id"),
+    boost::none, boost::none, boost::none, boost::none, boost::none, boost::none
+).then([](std::shared_ptr<GetComments_200_response> response) {
+    // This runs asynchronously when the request completes
+    if (response && response->comments) {
+        std::cout << "Found " << response->comments->size() << " comments" << std::endl;
+    }
+});
+
+// Execution continues immediately without blocking
+std::cout << "Request sent, continuing..." << std::endl;
+```
+
+### Choosing Between Synchronous and Asynchronous
+
+The choice depends on your runtime environment and application architecture:
+
+**`.get()` (Synchronous blocking)**
+- Blocks the calling thread until the HTTP request completes
+- Simpler code flow, easier to reason about
+- Suitable for dedicated worker threads, batch processing, or command-line tools
+- **Not suitable** for event loops, GUI threads, or single-threaded servers
+
+**`.then()` (Asynchronous non-blocking)**
+- Returns immediately, callback executes when request completes
+- Does not block the calling thread
+- Required for event-driven architectures, GUI applications, or single-threaded event loops
+- Allows chaining multiple operations
+- More complex control flow
+
+The SDK's test suite uses `.get()` exclusively, but this is appropriate for the test environment where blocking is acceptable.
+
 ## Notes
 
 ### Broadcast Ids