feat: provide a fieldlist to reduce response size

src/app/Http/Controllers/ItemController.php

@@ -5,16 +5,12 @@
 use App\Http\Controllers\ResponseController;
 use App\Models\Item;
 use App\Http\Resources\ItemResource;
+use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 
 class ItemController extends ResponseController
 {
-    /**
-     * Display a paginated listing of the resource.
-     *
-     * @return \Illuminate\Http\Response
-     */
-    public function index(Request $request)
+    public function index(Request $request): JsonResponse
     {
         $queryColumns = [
             'StoryId' => 'StoryId',
@@ -27,6 +23,8 @@ public function index(Request $request)
 
         $data = $this->getDataByRequest($request, $model, $queryColumns, $initialSortColumn);
 
+        $data = $this->filterDataByFieldlist($data, $request, ['StoryId', 'ItemId'], $initialSortColumn);
+
         if (!$data) {
             return $this->sendError('Invalid data', $request . ' not valid', 400);
         }
@@ -36,13 +34,7 @@ public function index(Request $request)
         return $this->sendResponseWithMeta($collection, 'Items fetched.');
     }
 
-    /**
-     * Display the specified resource.
-     *
-     * @param  int  $id
-     * @return \Illuminate\Http\Response
-     */
-    public function show($id)
+    public function show(int $id): JsonResponse
     {
         try {
             $data = Item::findOrFail($id);
@@ -54,14 +46,7 @@ public function show($id)
         }
     }
 
-    /**
-     * Update the specified resource in storage.
-     *
-     * @param  \Illuminate\Http\Request  $request
-     * @param  int  $id
-     * @return \Illuminate\Http\Response
-     */
-    public function update(Request $request, $id)
+    public function update(Request $request, int $id): JsonResponse
     {
         try {
             $item = Item::findOrfail($id);

src/app/Http/Controllers/ResponseController.php

@@ -158,4 +158,34 @@ protected function filterDataByQueries(
 
         return $filtered;
     }
+
+    protected function filterDataByFieldlist(
+        Collection $data,
+        Request $request,
+        array $defaults,
+        string $initialSortColumn
+    ): Collection
+    {
+        $queries = $request->query();
+
+        if (empty($queries['fieldlist'])) {
+            return $data;
+        }
+
+        $fieldlist = explode(',', $queries['fieldlist']);
+        $fieldlist = array_map('trim', $fieldlist);
+        $fieldlist[] = $queries['orderBy'] ?? $initialSortColumn;
+        $fieldlist = array_merge($defaults, $fieldlist);
+        $fieldlist = array_unique($fieldlist);
+        $dataArray = $data->toArray()[0] ?: $data->toArray();
+        $fieldsToRemove = array_filter(array_keys($dataArray), function($field) use ($fieldlist) {
+            return !in_array($field, $fieldlist);
+        });
+
+        $data->each(function($data) use ($fieldsToRemove) {
+            $data->makeHidden($fieldsToRemove);
+        });
+
+        return $data;
+    }
 }

src/app/Models/Item.php

@@ -76,9 +76,9 @@ public function properties(): BelongsToMany
 // to harmonize the API regarding the existent database schema
 // we make use some custom accessors and mutators
 
-    public function getDescriptionLangAttribute(): object
+    public function getDescriptionLangAttribute(): Language
     {
-        return $this->language()->first() ?: (object)[];
+        return $this->language()->first() ?: new Language();
     }
 
     public function getCompletionStatusAttribute(): CompletionStatus
@@ -92,10 +92,10 @@ public function getCompletionStatusAttribute(): CompletionStatus
                 'ColorCodeGradient'
             ]);
 
-        return $status;
+        return $status ?: new CompletionStatus();
     }
 
-    public function getTranscriptionAttribute(): Transcription|HtrDataRevision|array
+    public function getTranscriptionAttribute(): Transcription|HtrDataRevision
     {
         if ($this->TranscriptionSource === 'manual') {
             $manualTranscription = $this
@@ -108,7 +108,7 @@ public function getTranscriptionAttribute(): Transcription|HtrDataRevision|array
                 )
                 ->firstWhere('CurrentVersion', 1);
 
-            return $manualTranscription ? $manualTranscription : [];
+            return $manualTranscription ?: new Transcription();
         }
 
         if ($this->TranscriptionSource === 'htr') {
@@ -120,7 +120,7 @@ public function getTranscriptionAttribute(): Transcription|HtrDataRevision|array
                 ->latest()
                 ->first();
 
-            return $latest ? $latest->htrDataRevision->first() : [];
+            return $latest ? $latest->htrDataRevision->first() : new HtrData();
         }
 
         return [];
@@ -144,5 +144,4 @@ public function getPlacesAttribute(): Collection
     {
         return $this->places()->get() ?: [];
     }
-
 }

src/storage/api-docs/api-docs.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 
 info:
-  version: 1.49.0
+  version: 1.50.0
   title: Transcribathon Platform API v2
   description: This is the documentation of the Transcribathon API v2 used by [https:transcribathon.eu](https://transcribathon.eu/).<br />
          For authorization you can use the the bearer token you are provided with.

src/storage/api-docs/items-path.yaml

@@ -21,6 +21,10 @@ get:
       description: If set determines that the query (StoryId, ItemId) is a multiple query string and separated by this separator
       schema:
         type: string
+    - in: query
+      name: fieldlist
+      description: Comma-separated list of fields that will be shown in the response
+      type: string
   responses:
     200:
       description: Ok