Instruction on how to work with unsupported APIs (#1172)

- Document how to work with generic Data APIs that are currently
not supported by the Data SDK.
- Add an example on how to download the difference between two versions
of a catalog.
- Change numbering and indentation in
`docs/create-platform-client-settings.md`

Relates-To: OLPEDGE-2488

Signed-off-by: Halyna Dumych <[email protected]>

Author: HalynaDumych

docs/create-platform-client-settings.md

@@ -48,26 +48,26 @@ You need to create the `OlpClientSettings` object to get catalog and partition m
 
 5. (Optional) To configure a cache:
 
-    a. Create the `CacheSettings` instance with the cache that you want to enable and, if needed, the maximum cache size in bytes.
+    1. Create the `CacheSettings` instance with the cache that you want to enable and, if needed, the maximum cache size in bytes.
 
-      > #### Note
-      > By default, the downloaded data is cached in memory, and the maximum size of it is 1 MB.
+         > #### Note
+         > By default, the downloaded data is cached in memory, and the maximum size of it is 1 MB.
 
-      ```cpp
-      olp::cache::CacheSettings cache_settings;
-        //On iOS, the path is relative to the Application Data folder.
-      cache_settings.disk_path_mutable = "path to mutable cache";
-      cache_settings.disk_path_protected = "path to protected cache";
-      cache_settings.max_disk_storage = 1024ull * 1024ull * 32ull;
-      ```
+         ```cpp
+         olp::cache::CacheSettings cache_settings;
+         //On iOS, the path is relative to the Application Data folder.
+         cache_settings.disk_path_mutable = "path to mutable cache";
+         cache_settings.disk_path_protected = "path to protected cache";
+         cache_settings.max_disk_storage = 1024ull * 1024ull * 32ull;
+         ```
 
-    b. Add the `CacheSettings` instance to the `DefaultCache` constructor.
+    2. Add the `CacheSettings` instance to the `DefaultCache` constructor.
 
-    ```cpp
-    olp::client::OlpClientSettingsFactory::CreateDefaultCache(cache_settings);
-    ```
+       ```cpp
+       olp::client::OlpClientSettingsFactory::CreateDefaultCache(cache_settings);
+       ```
 
-    To learn how to get or change cache size, see [Work with a cache](https://developer.here.com/documentation/sdk-cpp/dev_guide/docs/work-with-cache.html).
+       To learn how to get or change cache size, see [Work with a cache](https://developer.here.com/documentation/sdk-cpp/dev_guide/docs/work-with-cache.html).
 
 6. Set up the `OlpClientSettings` object, and if you want to add the expiration limit for the data that is stored in the cache, set the `default_cache_expiration` to the needed expiration time.
 

docs/work-with-data-apis.md

@@ -0,0 +1,69 @@
+# Work with unsupported Data REST APIs
+
+HERE Data SDK for C++ supports only a limited number of Data REST APIs. You can find a list of them on our page with the [overall architecture](OverallArchitecture.md).
+
+If you need to work with any Data REST APIs that are currently not supported, you can use the `olp::client::OlpClient` class from our core library for the request. It has an easy-to-use interface and a retry mechanism that uses a recommended backoff strategy for subsequent requests.
+
+The example below demonstrates how to use the `olp::client::OlpClient` class from the Data SDK to call the API for downloading the difference between two versions of a versioned catalog.
+
+**Example. Download the difference between two versions of a catalog.**
+
+1. Create the `OlpClientSettings` object.
+
+   For instructions, see [Create platform client settings](create-platform-client-settings.md).
+
+2. Configure an `OlpClient` instance in one of the following ways:
+    - Use the `olp::client::ApiLookupClient` class to perform a request and get a preconfigured `olp::client::OlpClient` instance.
+    - Use a base URL:
+        1. Get the base URL from the lookup API service.
+
+            For instructions, see the [API Lookup API Developer's Guide](https://developer.here.com/documentation/api-lookup/dev_guide/index.html)
+        
+        2. Create an `OlpClient` instance with the client settings from step 1 and the base URL.
+
+            ```cpp
+            olp::client OlpClient client(client_settings, base_url);
+            ```
+
+3. Prepare the REST API request parameters and the metadata URL.
+
+    ```cpp
+    std::multimap<std::string, std::string> header_params;
+    header_params.emplace("Accept", "application/json");
+
+    // Replace "my_layer" with the actual layer name.
+    std::string metadata_url = "/layers/my_layer/changes";
+
+    std::multimap<std::string, std::string> query_params;
+
+    // Required parameters.
+    query_params.emplace("startVersion", "0");
+    query_params.emplace("endVersion", "1");
+
+    // Optional parameters.
+    query_params.emplace("additionalFields", "dataSize,checksum");
+    query_params.emplace("billingTag", "Billing1234");
+
+    // Can be used to cancel the ongoing request. Needs to be triggered
+    // from another thread as `olp::client::OlpClient::CallApi()` is a blocking call.
+    CancellationContext context;
+    olp::client::HttpResponse response = client.CallApi(
+        metadata_url, "GET", query_params, header_params, {}, nullptr, "", context);
+    ```
+
+4. Check the response and, if needed, parse JSON.
+
+    ```cpp
+    if (response.GetStatus() != olp::http::HttpStatusCode::OK) {
+        // If the response is not OK, handle error cases.
+    }
+    ```
+
+5. If the check passed and the status of the received `olp::client::HttpResponse` is `olp::http::HttpStatusCode::OK` (that is 200 OK), extract the encoded JSON from the response and parse it using RapidJSON or any other JSON parsing library.
+
+    ```cpp
+    std::string response_json;
+    response.GetResponse(response_json);
+    ```
+
+    You get the information on the difference between the specified versions of the versioned catalog.