From 5ecd41b8370a4fdd73e9c3fa26c8a45480ef7739 Mon Sep 17 00:00:00 2001
From: Christopher Green <cgreen@datalogics.com>
Date: Wed, 26 Jun 2024 12:13:51 -0500
Subject: [PATCH] Add explanatory comments to request-status samples

---
 .../Endpoint Examples/Multipart Payload/request-status.js   | 5 +++++
 PHP/Endpoint Examples/Multipart Payload/request-status.php  | 6 +++++-
 .../Endpoint Examples/Multipart Payload/request-status.py   | 2 ++
 cURL/Endpoint Examples/Multipart Payload/request-status.sh  | 6 ++++++
 4 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/JavaScript/Endpoint Examples/Multipart Payload/request-status.js b/JavaScript/Endpoint Examples/Multipart Payload/request-status.js
index e0f7789..5bf214d 100644
--- a/JavaScript/Endpoint Examples/Multipart Payload/request-status.js	
+++ b/JavaScript/Endpoint Examples/Multipart Payload/request-status.js	
@@ -23,6 +23,8 @@ const pollUntilFulfilled = async (requestId) => {
   };
   requestStatusResponse = await axios(pollConfig);
   let status = requestStatusResponse.data.status;
+
+  // This example will repeat the GET request until the BMP request is completed.
   while (status === "pending") {
     console.log(JSON.stringify(requestStatusResponse.data));
     await sleep(5000);
@@ -34,6 +36,7 @@ const pollUntilFulfilled = async (requestId) => {
 
 const demoApiPolling = async () => {
   try {
+    // Send a request with the Response-Type header (using /bmp as an arbitrary example)
     const bmpRequestData = new FormData();
     bmpRequestData.append("file", fs.createReadStream(pathToFile));
   
@@ -50,6 +53,8 @@ const demoApiPolling = async () => {
     };
     bmpResponse = await sendBmpReq(bmpConfig);
     console.log(JSON.stringify(bmpResponse.data));
+    
+    // Get the request ID from the initial response.
     const requestId = bmpResponse.data.requestId;
     await pollUntilFulfilled(requestId);
   } catch (err) {
diff --git a/PHP/Endpoint Examples/Multipart Payload/request-status.php b/PHP/Endpoint Examples/Multipart Payload/request-status.php
index 353d2e7..e6136c0 100644
--- a/PHP/Endpoint Examples/Multipart Payload/request-status.php	
+++ b/PHP/Endpoint Examples/Multipart Payload/request-status.php	
@@ -11,7 +11,7 @@
 
 $headers = [
   'Api-Key' => $apiKey,
-  'response-type' => 'requestId'
+  'response-type' => 'requestId' // Use this header to obtain a request status.
 ];
 
 $pngOptions = [
@@ -27,6 +27,7 @@
   ]
 ];
 
+// Using /png as an arbitrary example, send a request with the Request-Type header.
 $pngRequest = new Request('POST', 'https://api.pdfrest.com/png', $headers);
 
 $pngResponse = $client->sendAsync($pngRequest, $pngOptions)->wait();
@@ -34,8 +35,10 @@
 echo $pngResponse->getBody();
 echo "\r\n";
 
+// Get the request ID from the response.
 $requestId = json_decode($pngResponse->getBody())->{'requestId'};
 
+// Get the status of the PNG request by its ID.
 $request_status_endpoint_url = 'https://api.pdfrest.com/request-status/'.$requestId;
 
 $headers = [
@@ -48,6 +51,7 @@
 
 $status = json_decode($res->getBody())->{'status'};
 
+// This example repeats the status request until the request is fulfilled.
 while (strcmp($status, "pending") == 0):
   echo $res->getBody(); // Output the response body, which contains the status information.
   echo "\r\n";
diff --git a/Python/Endpoint Examples/Multipart Payload/request-status.py b/Python/Endpoint Examples/Multipart Payload/request-status.py
index 3ca13cf..7082de1 100644
--- a/Python/Endpoint Examples/Multipart Payload/request-status.py	
+++ b/Python/Endpoint Examples/Multipart Payload/request-status.py	
@@ -14,6 +14,7 @@
     }
 )
 
+# Send a request to a pdfRest tool with the Response-Type header to get a request ID,
 pdfa_headers = {
     'Accept': 'application/json',
     'Content-Type': mp_encoder_pdfa.content_type,
@@ -44,6 +45,7 @@
     if response.ok:
         response_json = response.json()
         while response_json["status"] == "pending":
+            # This example will get the request status every 5 seconds until the request is completed.
             print(json.dumps(response_json, indent = 2))
             time.sleep(5)
             response = requests.get(api_polling_endpoint_url, headers=headers)
diff --git a/cURL/Endpoint Examples/Multipart Payload/request-status.sh b/cURL/Endpoint Examples/Multipart Payload/request-status.sh
index 811ed90..f6a648c 100755
--- a/cURL/Endpoint Examples/Multipart Payload/request-status.sh	
+++ b/cURL/Endpoint Examples/Multipart Payload/request-status.sh	
@@ -2,6 +2,8 @@
 
 API_KEY="xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
 
+# Send a request with the response-type header.
+
 REQUEST_ID=$(curl -X POST "https://api.pdfrest.com/pdfa" \
   -H "Accept: application/json" \
   -H "Content-Type: multipart/form-data" \
@@ -12,11 +14,15 @@ REQUEST_ID=$(curl -X POST "https://api.pdfrest.com/pdfa" \
   -F "output=example_out" \
   | jq -r '.requestId')
 
+# Get the request status at /request-status
+
 RESPONSE=$(curl -X GET "https://api.pdfrest.com/request-status/$REQUEST_ID" \
   -H "Api-Key: $API_KEY")
 echo $RESPONSE
 STATUS=$(echo $RESPONSE | jq -r '.status')
 
+# This example repeats the GET request until the Toolkit request is completed.
+
 while [ $STATUS = "pending" ]
 do
   sleep 5