Add in cacheable json response

[pingevt]

Addresses: #15

This pull request introduces significant updates to the bc_api_example module, focusing on adding cacheable API endpoints, improving response handling, and enhancing test coverage. Key changes include the addition of a new API controller with caching capabilities, the introduction of a reusable CacheableJsonResponseTrait, and updates to tests to validate the new functionality.

API Enhancements

• Added two new cacheable API endpoints (/api/cacheable/pirates and /api/cacheable/pirates/{nid}) in bc_api_example.routing.yml with authentication and permission requirements. These endpoints are handled by the new ApiControllerCacheableResponsePirateExample class. [1] [2]
• Implemented CacheableJsonResponseTrait to simplify creating cacheable JSON responses and managing cache metadata. This trait is now used in the new controller.
• Updated the base API controller (ApiControllerBase) to support cacheable responses by overriding the createResponse method. [1] [2] [3]

Code Improvements

• Added caching logic to the getResourceListQueryResult method in the new controller to filter and paginate pirate nodes based on status and type.
• Improved error handling in the ApiSubscriber by using getPathInfo() for path validation and fixing a logging issue for 404 errors. [1] [2]

Testing Enhancements

• Added a new unit test class, CacheableJsonResponseTraitTest, to validate the behavior of the CacheableJsonResponseTrait.
• Updated functional tests in ResponseTests to include a new test for the cacheable pirates API endpoint and made minor adjustments to existing tests. [1] [2]
• Applied type hinting and modernized test setup methods in functional and unit tests. [1] [2]

Miscellaneous

• Added a dependency on the taxonomy module in bc_api_example.info.yml to support filtering by taxonomy ID.
• Changed the default theme for functional tests from classy to stable9.

[Copilot]

Pull Request Overview

Adds support for cacheable JSON responses across the API layer, updating controllers, interfaces, and subscribers, and including new tests and example routes.

• Introduced CacheableJsonResponseTrait and added createResponse() to the controller interface and base class
• Updated ApiControllerBase to delegate to createResponse() and wired in cache metadata
• Added unit and functional tests for cacheable responses, and example implementations and routes

Reviewed Changes

Copilot reviewed 11 out of 16 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/CacheableJsonResponseTrait.php	New trait to build cacheable JSON responses
src/Controller/ApiControllerInterface.php	Added createResponse(): Response to the interface
src/Controller/ApiControllerBase.php	Switched to createResponse() and implemented default
tests/src/Unit/CacheableJsonResponseTraitTest.php	Unit tests for cache metadata merging and response class
tests/src/Functional/ResponseTests.php	Functional test for cacheable pirates endpoint
modules/bc_api_example/...CacheableResponsePirateExample.php	Example controller using the cacheable trait
modules/bc_api_example/bc_api_example.routing.yml	Routes for cacheable endpoints

Comments suppressed due to low confidence (4)

src/Controller/ApiControllerInterface.php:87

• Missing import of the Response class. Add use Symfony\Component\HttpFoundation\Response; at the top of this interface so the return type is recognized.

  public function createResponse(): Response;

src/Controller/ApiControllerBase.php:467

• [nitpick] This commented-out instantiation is dead code. Consider removing it to improve readability and reduce clutter.

    // $response = new JsonResponse($this->return_data);

tests/src/Functional/ResponseTests.php:91

• [nitpick] The commented-out drupalLogin call may confuse future maintainers. Remove it or add a comment explaining why login is skipped.

    // $this->drupalLogin($user);

tests/src/Functional/ResponseTests.php:115

• [nitpick] Similar to above, this commented login should be documented or removed to keep the test clear.

    // $this->drupalLogin($user);

[aasarava]

Sorry for the slow review. Looks great overall. I left some minor/nitpicky notes, but nothing's a blocker.

[aasarava]

I'm confused by this comment, because lines 92-94 show a clear reason for overriding the method.

[pingevt]

hmmm... ok the non-cacheable one makes sense. But this one doesn't. Esp. since I'm using a trait and not extending the class. 🤔

[pingevt]

Well... that "example" should be added to the trait. then the comment will be valid then.

[aasarava]

i know this is just an example, but should we recommend that accessCheck() be FALSE? otherwise, the results could vary based on which user triggers the API call, right?