Add in cacheable json response

modules/bc_api_example/bc_api_example.info.yml

@@ -6,6 +6,7 @@ core_version_requirement: ^10 || ^11
 package: Bluecadet
 
 dependencies:
+  - drupal:taxonomy
   - bc_api_base:bc_api_base
 
 configure: null

modules/bc_api_example/bc_api_example.routing.yml

@@ -20,3 +20,26 @@ bc_api_example.pirates_detail:
     parameters:
       nid:
         type: entity:node
+
+bc_api_example.cacheable.pirates:
+  path: '/api/cacheable/pirates'
+  methods: [GET, HEAD]
+  defaults:
+    _controller: '\Drupal\bc_api_example\Controller\ApiControllerCacheableResponsePirateExample:getResourceList'
+  requirements:
+    _permission: 'use api'
+  options:
+    _auth: [ 'key_auth' ]
+
+bc_api_example.cacheable.pirates_detail:
+  path: '/api/cacheable/pirates/{nid}'
+  methods: [GET, HEAD]
+  defaults:
+    _controller: '\Drupal\bc_api_example\Controller\ApiControllerCacheableResponsePirateExample:getResource'
+  requirements:
+    _permission: 'use api'
+  options:
+    _auth: [ 'key_auth' ]
+    parameters:
+      nid:
+        type: entity:node

modules/bc_api_example/src/Controller/ApiControllerCacheableResponsePirateExample.php

@@ -0,0 +1,170 @@
+<?php
+
+namespace Drupal\bc_api_example\Controller;
+
+use Drupal\bc_api_base\Controller\ApiControllerBase;
+use Drupal\bc_api_base\CacheableJsonResponseTrait;
+
+/**
+ * Example API Controller Class.
+ *
+ * @ApiDoc(
+ *   params = {
+ *     @ApiParam(
+ *       name = "status",
+ *       type = "bool",
+ *       description = "Filter on node status.",
+ *       default = "TRUE",
+ *     ),
+ *     @ApiParam(
+ *       name = "nat",
+ *       type = "int",
+ *       description = "Filter on nationality. This should use the taxonomy id of the nationality.",
+ *     ),
+ *   }
+ * )
+ */
+class ApiControllerCacheableResponsePirateExample extends ApiControllerBase {
+
+  use CacheableJsonResponseTrait;
+
+  /**
+   * {@inheritdoc}
+   */
+  public function getApiCacheTime($id = NULL) {
+    // Parent method looks at settings form and takes into account list or
+    // detail.
+    return 0;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function getCacheId() {
+    // This should be a unique string, characters only.
+    $cid = "yo-ho-ho";
+
+    if (!empty($this->params)) {
+      $cid .= ":" . implode(":", $this->params);
+    }
+
+    $cid .= ":page-" . $this->page;
+    $cid .= ":limit-" . $this->limit;
+
+    return $cid;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function initCacheTags() {
+    $this->cacheTags = [
+      'myAwesomeCoolCacheTag',
+    ];
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function setParams() {
+    // It would be good to always run this.
+    parent::setParams();
+
+    $this->privateParams['status'] = 1;
+
+    // Here we also want to handle any bad param errors...
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function getDefaultPlatform() {
+    return "cinder";
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function getResourceQueryResult() {
+    // Just having this here as an example.
+    // Most times no need to override this method.
+    parent::getResourceQueryResult();
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function getResourceListQueryResult() {
+    // This method should be overridden for any endpoint.
+    $query = $this->entityTypeManager->getStorage('node')->getQuery();
+    $query->accessCheck(TRUE);
+    $query->condition('status', $this->privateParams['status']);
+    $query->condition('type', 'pirate');
+
+    $count_query = clone $query;
+
+    $query->range(($this->page * $this->limit), $this->limit);
+    $entity_ids = $query->execute();
+
+    // Must set total result count so we can properly page.
+    $this->resultTotal = (int) $count_query->count()->execute();
+
+    // Process Items.
+    $nodes = $this->entityTypeManager->getStorage('node')->loadMultiple($entity_ids);
+
+    $this->rawData = $nodes;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function buildAllResourceData() {
+    $data = [];
+
+    foreach ($this->rawData as $node) {
+      $this->cacheTags = array_merge($this->cacheTags, $node->getCacheTags());
+      $this->addCacheableDependency($node);
+      $created_changed = $this->transformer->createdChangedFieldVals($node);
+
+      $item = [
+        'nid' => (int) $node->id(),
+        'cms_title' => $node->label(),
+        'created' => $created_changed[0],
+        'updated' => $created_changed[1],
+      ];
+      $data[] = $item;
+    }
+
+    $this->data = $data;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function buildLinks() {
+    // This method should be overridden for any endpoint.
+    $base_url = $this->request->getSchemeAndHttpHost() . $this->request->getPathInfo();
+    $tmp_query_params = $this->params;
+    $tmp_query_params['platform'] = $this->platform;
+    $tmp_query_params['limit'] = $this->limit;
+
+    if ($this->page == 0) {
+      $this->prev = "";
+    }
+    else {
+      $tmp_query_params['page'] = $this->page - 1;
+      $this->prev = $base_url . "?" . http_build_query($tmp_query_params);
+    }
+
+    if ($this->resultTotal > (($this->page + 1) * $this->limit)) {
+      $tmp_query_params['page'] = $this->page + 1;
+      $this->next = $base_url . "?" . http_build_query($tmp_query_params);
+    }
+    else {
+
+      $this->next = "";
+    }
+
+  }
+
+}

modules/bc_api_example/src/Controller/ApiControllerPirateExample.php

@@ -38,7 +38,8 @@ public function getApiCacheTime($id = NULL) {
    * {@inheritdoc}
    */
   public function getCacheId() {
-    $cid = "SOMETHING_UNIQUE";
+    // This should be a unique string, characters only.
+    $cid = "pirates";
 
     if (!empty($this->params)) {
       $cid .= ":" . implode(":", $this->params);
@@ -93,6 +94,7 @@ public function getResourceQueryResult() {
   public function getResourceListQueryResult() {
     // This method should be overridden for any endpoint.
     $query = $this->entityTypeManager->getStorage('node')->getQuery();
+    $query->accessCheck(TRUE);
     $query->condition('status', $this->privateParams['status']);
     $query->condition('type', 'pirate');
 

src/CacheableJsonResponseTrait.php

@@ -0,0 +1,92 @@
+<?php
+
+namespace Drupal\bc_api_base;
+
+use Drupal\Core\Cache\CacheableJsonResponse;
+use Drupal\Core\Cache\CacheableMetadata;
+use Symfony\Component\HttpFoundation\Response;
+
+/**
+ * Trait CacheableJsonResponseTrait.
+ *
+ * This trait provides a way to create cacheable JSON responses. It allows for
+ * the addition of cacheable metadata and dependencies to the response, ensuring
+ * that the response can be cached appropriately.
+ */
+trait CacheableJsonResponseTrait {
+
+  /**
+   * Cacheable metadata for the response.
+   *
+   * @var \Drupal\Core\Cache\CacheableMetadata
+   */
+  protected $cacheMetadata = NULL;
+
+  /**
+   * Returns the cacheable metadata for the response.
+   *
+   * When building any data, cacheable metadata should be set from there. And it
+   * will be applied when the request is altered.
+   *
+   * @return \Drupal\Core\Cache\CacheableMetadata
+   */
+  protected function getCacheableMetadata(): CacheableMetadata {
+    if (!isset($this->cacheMetadata)) {
+      $this->cacheMetadata = new CacheableMetadata();
+    }
+    return $this->cacheMetadata;
+  }
+
+  /**
+   * Adds a dependency on an object: merges its cacheability metadata.
+   *
+   * For instance, when a response depends on some configuration, an entity, or
+   * an access result, we must make sure their cacheability metadata is present
+   * on the response. This method makes doing that simple.
+   *
+   * @param \Drupal\Core\Cache\CacheableDependencyInterface|mixed $dependency
+   *   The dependency. If the object implements CacheableDependencyInterface,
+   *   then its cacheability metadata will be used. Otherwise, the passed in
+   *   object must be assumed to be uncacheable, so max-age 0 is set.
+   *
+   * @return $this
+   */
+  public function addCacheableDependency($dependency) {
+
+    $this->cacheMetadata = $this->getCacheableMetadata()->merge(CacheableMetadata::createFromObject($dependency));
+
+    return $this;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function getResourceQueryResult() {
+    parent::getResourceQueryResult();
+
+    // If the resource is set, add it as a cacheable dependency.
+    if (isset($this->resource) && !empty($this->resource)) {
+      $this->addCacheableDependency($this->resource);
+    }
+  }
+
+  /**
+   * {@inheritdoc}
+   *
+   * Override the base classes response, to create a cacheable response.
+   */
+  public function createResponse(): Response {
+    $response = new CacheableJsonResponse($this->return_data);
+
+    // Attach cache metadata if available.
+    if ($cache_metadata = $this->getCacheableMetadata()) {
+      $response->addCacheableDependency($cache_metadata);
+    }
+
+    // Alter it.
+    $this->responseAlter($response);
+
+    return $response;
+  }
+
+}

src/Controller/ApiControllerBase.php

@@ -311,7 +311,7 @@
     }
 
     $this->platform = $platform;
     $this->transformer->setPlatform($platform);
   }
 
   /**
@@ -341,9 +341,9 @@
   public function autoParams() {
 
     // @TODO: Why aren't these autoloaded???
     new ApiDoc([]);
     new ApiBaseDoc([]);
     new ApiParam([]);
 
     $reader = new SimpleAnnotationReader();
     $reader->addNamespace('Drupal\bc_api_base\Annotation');
@@ -464,9 +464,8 @@
       return [];
     }
 
-    $response = new JsonResponse($this->return_data);
-    // Alter it.
-    $this->responseAlter($response);
+    // $response = new JsonResponse($this->return_data);
+    $response = $this->createResponse();
 
     return $response;
   }
@@ -533,9 +532,7 @@
       return [];
     }
 
-    $response = new JsonResponse($this->return_data);
-    // Alter it.
-    $this->responseAlter($response);
+    $response = $this->createResponse();
 
     return $response;
   }
@@ -589,6 +586,19 @@
     $this->next = "";
   }
 
+  /**
+   * {@inheritdoc}
+   */
+  public function createResponse(): Response {
+    $response = new JsonResponse($this->return_data);
+    $response->setStatusCode($this->return_data['status']);
+
+    // Allow subclasses to alter it.
+    $this->responseAlter($response);
+
+    return $response;
+  }
+
   /**
    * {@inheritdoc}
    */

src/Controller/ApiControllerInterface.php

@@ -74,8 +74,23 @@ public function getResource(Request $request);
    */
   public function getResourceList(Request $request);
 
+  /**
+   * Create the response object.
+   *
+   * We allow subclasses to override this method if they need to create
+   * different types of responses, however, they can also alter the response
+   * later, if they only need minor changes.
+   *
+   * @return Symfony\Component\HttpFoundation\Response
+   *   The response object.
+   */
+  public function createResponse(): Response;
+
   /**
    * Alter the response object before executing.
+   *
+   * @param \Symfony\Component\HttpFoundation\Response $response
+   *   The response object to alter.
    */
   public function responseAlter(Response $response);