feat(api): implemented HTTP-native conditional caching for paginated API list endpoints

Author: thorsten

phpmyfaq/src/phpMyFAQ/Controller/Api/AbstractApiController.php

@@ -154,7 +154,15 @@ protected function paginatedResponse(
             filters: $options->filters,
         );
 
-        return new JsonResponse($responseData, $options->status);
+        $response = new JsonResponse($responseData, $options->status);
+        $response->setPublic();
+        $response->setMaxAge(0);
+        $response->headers->addCacheControlDirective('must-revalidate');
+        $response->setVary(['Accept-Language'], false);
+        $response->setEtag($this->createResponseEtag($responseData));
+        $response->isNotModified($request);
+
+        return $response;
     }
 
     /**
@@ -192,4 +200,15 @@ protected function errorResponse(
 
         return new JsonResponse($responseData, $status);
     }
+
+    /**
+     * Creates a stable ETag for a JSON API response payload.
+     *
+     * @param array $responseData
+     * @return string
+     */
+    private function createResponseEtag(array $responseData): string
+    {
+        return hash('sha256', json_encode($responseData, JSON_THROW_ON_ERROR));
+    }
 }

tests/phpMyFAQ/Controller/Api/AbstractApiControllerTest.php

@@ -113,6 +113,42 @@ public function testPaginatedResponseReturnsEnvelopeWithMetadata(): void
         self::assertSame(5, $payload['meta']['pagination']['total']);
         self::assertSame('name', $payload['meta']['sorting']['field']);
         self::assertTrue($payload['meta']['filters']['active']);
+        self::assertStringContainsString('public', (string) $response->headers->get('Cache-Control'));
+        self::assertStringContainsString('max-age=0', (string) $response->headers->get('Cache-Control'));
+        self::assertStringContainsString('must-revalidate', (string) $response->headers->get('Cache-Control'));
+        self::assertSame('Accept-Language', (string) $response->headers->get('Vary'));
+        self::assertNotNull($response->headers->get('ETag'));
+    }
+
+    public function testPaginatedResponseReturnsNotModifiedForMatchingIfNoneMatch(): void
+    {
+        $controller = new AbstractApiControllerTestStub();
+        $request = new Request(['page' => '1', 'per_page' => '2'], [], [], [], [], ['REQUEST_URI' => '/api/items']);
+        $pagination = $controller->getPaginationRequestPublic($request);
+
+        $initialResponse = $controller->paginatedResponsePublic(
+            $request,
+            [['id' => 1], ['id' => 2]],
+            2,
+            $pagination,
+        );
+        $etag = $initialResponse->headers->get('ETag');
+
+        self::assertNotNull($etag);
+
+        $conditionalRequest = new Request(['page' => '1', 'per_page' => '2'], [], [], [], [], ['REQUEST_URI' => '/api/items']);
+        $conditionalRequest->headers->set('If-None-Match', $etag);
+
+        $response = $controller->paginatedResponsePublic(
+            $conditionalRequest,
+            [['id' => 1], ['id' => 2]],
+            2,
+            $pagination,
+        );
+
+        self::assertSame(Response::HTTP_NOT_MODIFIED, $response->getStatusCode());
+        self::assertSame('', (string) $response->getContent());
+        self::assertSame($etag, $response->headers->get('ETag'));
     }
 
     public function testApiResponseReturnsSuccessEnvelope(): void

tests/phpMyFAQ/Controller/Api/CategoryControllerWebTest.php

@@ -40,6 +40,28 @@ public function testCategoriesEndpointReturnsJson(): void
         self::assertResponseIsSuccessful($response);
         self::assertSame('application/json', $response->headers->get('Content-Type'));
         self::assertJson((string) $response->getContent());
+        self::assertNotNull($response->headers->get('ETag'));
+        self::assertSame('Accept-Language', (string) $response->headers->get('Vary'));
+    }
+
+    public function testCategoriesEndpointReturnsNotModifiedWhenEtagMatches(): void
+    {
+        $this->getConfiguration('api')->getAll();
+        $this->overrideConfigurationValues(['api.enableAccess' => true], 'api');
+
+        $initialResponse = $this->requestApi('GET', '/v3.2/categories');
+        $etag = $initialResponse->headers->get('ETag');
+
+        self::assertResponseIsSuccessful($initialResponse);
+        self::assertNotNull($etag);
+
+        $response = $this->requestApi('GET', '/v3.2/categories', [], [
+            'HTTP_IF_NONE_MATCH' => $etag,
+        ]);
+
+        self::assertResponseStatusCodeSame(304, $response);
+        self::assertSame('', (string) $response->getContent());
+        self::assertSame($etag, $response->headers->get('ETag'));
     }
 
     public function testCreateWithoutTokenReturnsUnauthorizedJson(): void