FEAT: made helper API endpoints compliant to json API standard, by putting no resource record responses in the metadata

Author: jessevz

src/inc/apiv2/common/AbstractBaseAPI.class.php

@@ -659,7 +659,7 @@ protected function object2Array(object $object, array $expands = []): array
   /**
    * Uniform conversion of php array to JSON output 
    */
-  protected function ret2json(array $result): string
+  protected static function ret2json(array $result): string
   {
     return json_encode($result, JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR) . PHP_EOL;
   }
@@ -1159,7 +1159,7 @@ protected function getQueryParameterFamily(Request $request, string $family): ar
     return $retval;
   }
 
-  static function createJsonResponse(array $data = [], array $links = [], array $included = []) {
+  static function createJsonResponse(array $data = [], array $links = [], array $included = [], array $meta = []) {
     $response = [
         "jsonapi" => [
           "version" => "1.1",
@@ -1173,6 +1173,10 @@ static function createJsonResponse(array $data = [], array $links = [], array $i
       $response["links"] = $links;
     }
 
+    if(!empty($meta)) {
+      $response["meta"] = $meta;
+    }
+
     $response["data"] = $data;
 
     if (!empty($included)) {
@@ -1251,6 +1255,15 @@ protected static function getOneResource(object $apiClass, object $object, Reque
       //case of a POST request
   }
 
+  //Meta response for helper functions that do not respond with resource records
+  protected static function getMetaResponse(array $meta, Request $request, Response $response, int $statusCode=200) {
+    $ret = self::createJsonResponse($meta=$meta);
+    $body = $response->getBody();
+    $body->write(self::ret2json($ret));
+
+    return $response->withStatus($statusCode)->withHeader("Content-Type", "application/vnd.api+json");
+  }
+
   /**
    * Override-able activated methods 
    */

src/inc/apiv2/common/AbstractHelperAPI.class.php

@@ -17,7 +17,7 @@
 use DBA\User;
 
 abstract class AbstractHelperAPI extends AbstractBaseAPI {
-  abstract public function actionPost(array $data): object|null;
+  abstract public function actionPost(array $data): object|array|null;
 
 
   /* Chunk API endpoint specific call to abort chunk */
@@ -43,9 +43,15 @@ public function processPost(Request $request, Response $response, array $args):
       return $response->withStatus(204);
     }
 
+
     /* Succesful executed action of create */
-    $apiClass = new ($this->container->get('classMapper')->get($newObject::class))($this->container);
-    return self::getOneResource($apiClass, $newObject, $request, $response);
+    if (is_object($newObject)) {
+      $apiClass = new ($this->container->get('classMapper')->get($newObject::class))($this->container);
+      return self::getOneResource($apiClass, $newObject, $request, $response);
+    /* A meta response of a helper function */
+    } elseif (is_array($newObject)) {
+      return self::getMetaResponse($newObject, $request, $response);
+    }
   }  
 
   /**

src/inc/apiv2/helper/abortChunk.routes.php

@@ -24,7 +24,7 @@ public function getFormFields(): array {
     ];
   }
 
-  public function actionPost(array $data): object|null {
+  public function actionPost(array $data): object|array|null {
     $chunk = self::getChunk($data[Chunk::CHUNK_ID]);
 
     TaskUtils::abortChunk($chunk->getId(), $this->getCurrentUser());

src/inc/apiv2/helper/assignAgent.routes.php

@@ -25,7 +25,7 @@ public function getFormFields(): array {
     ];
   }
 
-  public function actionPost($data): array|null {
+  public function actionPost($data): object|array|null {
     AgentUtils::assign($data[Agent::AGENT_ID], $data[Task::TASK_ID], $this->getCurrentUser());
 
     # TODO: Check how to handle custom return messages that are not object, probably we want that to be in some kind of standardized form.

src/inc/apiv2/helper/createSuperHashlist.routes.php

@@ -34,7 +34,7 @@ public function getFormFields(): array
     ];
   }
 
-  public function actionPost($data): object|null {
+  public function actionPost($data): object|array|null {
     /* Validate incoming hashlists */
     $hashlistIds = [];
     foreach($data["hashlistIds"] as $hashlistId) {

src/inc/apiv2/helper/createSupertask.routes.php

@@ -34,7 +34,7 @@ public function getFormFields(): array
     ];
   }
 
-  public function actionPost($data): object|null {
+  public function actionPost($data): object|array|null {
     $supertaskTemplate = self::getSupertask($data["supertaskTemplateId"]);
     $hashlist = self::getHashlist($data[Hashlist::HASHLIST_ID]);
     $crackerBinary = self::getCrackerBinary($data["crackerVersionId"]);

src/inc/apiv2/helper/exportCrackedHashes.routes.php

@@ -26,11 +26,11 @@ public function getFormFields(): array
     ];
   }
 
-  public function actionPost($data): array|null {
+  public function actionPost($data): object|array|null {
     $hashlist = self::getHashlist($data[Hashlist::HASHLIST_ID]);
 
     $file = HashlistUtils::export($hashlist->getId(), $this->getCurrentUser());
-    return $this->object2Array($file);
+    return $file;
   }
 }
 

src/inc/apiv2/helper/exportLeftHashes.routes.php

@@ -26,12 +26,12 @@ public function getFormFields(): array
     ];
   }
 
-  public function actionPost($data): array|null {
+  public function actionPost($data): object|array|null {
     $hashlist = self::getHashlist($data[Hashlist::HASHLIST_ID]);
 
     $file = HashlistUtils::leftlist($hashlist->getId(), $this->getCurrentUser());
 
-    return $this->object2Array($file);
+    return $file;
   }
 }
 

src/inc/apiv2/helper/exportWordlist.routes.php

@@ -26,12 +26,12 @@ public function getFormFields(): array
     ];
   }
 
-  public function actionPost($data): array|null {
+  public function actionPost($data): object|array|null {
     $hashlist = self::getHashlist($data[Hashlist::HASHLIST_ID]);
 
     $arr = HashlistUtils::createWordlists($hashlist->getId(), $this->getCurrentUser());
 
-    return $this->object2Array($arr[2]);
+    return $arr[2];
   }
 }
 

src/inc/apiv2/helper/importCrackedHashes.routes.php

@@ -26,12 +26,11 @@ public function getFormFields(): array {
     ];
   }
 
-  public function actionPost($data): array|null {
+  public function actionPost($data): object|array|null {
     $hashlist = self::getHashlist($data[Hashlist::HASHLIST_ID]);
 
     $result = HashlistUtils::processZap($hashlist->getId(), $data["separator"], "paste", ["hashfield" => $data["sourceData"]], [], $this->getCurrentUser());
 
-    # TODO: Check how to handle custom return messages that are not object, probably we want that to be in some kind of standardized form.
     return [
       "totalLines" => $result[0],
       "newCracked" => $result[1],