Improve the developer experience for returning data in a resource

Here's a patch. The code was reduced to calling one function exposed from the JSON:API EntityResource controller.

    $node_storage = $this->entityTypeManager->getStorage('node');
    $content_query = $node_storage->getQuery()
      ->condition('status', NodeInterface::PUBLISHED)
      ->condition('uid', $user->id());

    $nodes = $this->loadEntityResourceObjectsWithAccess($node_storage, $content_query->execute());
    $data = new ResourceObjectData($nodes);

+++ b/src/Resource/EntityResourceBase.php
@@ -38,8 +50,45 @@ abstract class EntityResourceBase extends ResourceBase {
+  protected function loadEntityResourceObjectsWithAccess(EntityStorageInterface $storage, array $ids, $load_latest_revisions = FALSE): array {
+    return $this->entityResourceShim->loadEntitiesWithAccess($storage, $ids, $load_latest_revisions);

This was renamed from the parent so that it makes more sense.

loadEntitiesWithAccess actually returns resource objects, not entities.

+++ b/src/Resource/EntityResourceBase.php
@@ -23,12 +44,16 @@ abstract class EntityResourceBase extends ResourceBase {
+    $this->entityAccessChecker = $entity_access_checker;
+    assert(is_string(static::$entityTypeId) && $this->entityTypeManager->hasDefinition(static::$entityTypeId), 'Extensions of \Drupal\jsonapi_resource\Resource\EntityResourceBase must set the static property $entityTypeId to a valid entity type ID or be declared abstract.');

+++ b/tests/modules/jsonapi_resources_test/src/Resource/AuthorContent.php
@@ -12,6 +11,11 @@ use Symfony\Component\HttpFoundation\Request;
+  protected static $entityTypeId = 'node';

This assumes the EntityResource will only perform storage for a single entity type.

I guess that kind of maps how dataProviders in Restful work? But it feels weird that the resource is dictated by a static property.

• Maybe instead of passing OffsetPaginationEntityQueryModifier it should instead be a route option in routing.yml, like _offset_pagination: true.

  I agree it'd be nice to have pagination just work. My fear is that we may start adding a lot of arbitrary route defaults that need documentation. Especially as I explore adding magicalness to POST/PATCH.

  This is why I thought of originally having plugins. Because it makes this a flag method on the plugin.

• This is tightly coupled to the entity query. I could see having the pager beneficial for anything implementing a query interface, such as custom Search API queries (I think the Search API query abstraction implements a relatable interface.) This would fix pagination for a custom Solr resource per https://glamanate.com/blog/using-json-api-query-your-search-api-indexes

• +++ b/jsonapi_resources.services.yml
  --- /dev/null
  +++ b/src/EntityQuery/CallableEntityQueryModifier.php
  
  +++ b/src/Resource/EntityResourceBase.php
  @@ -38,8 +68,184 @@ abstract class EntityResourceBase extends ResourceBase {
  +  private function loadResourceObjectsByEntityIds($entity_type_id, array $ids, $load_latest_revisions = FALSE, $check_access = TRUE): array {
  +    $storage = $this->entityTypeManager->getStorage($entity_type_id);
  ...
  +  protected function createResourceObjectFromEntity(EntityInterface $entity, $check_access = TRUE) {
  +    $resource_objects = $this->createResourceObjectsFromEntities([$entity], $check_access);
  ...
  +  protected function createResourceObjectsFromEntities(array $entities, $check_access = TRUE) {
  +    $resource_objects = [];
  +    foreach ($entities as $entity) {
  ...
  +  private function executeQueryInRenderContext(QueryInterface $query, CacheableMetadata $query_cacheability) {
  +    $context = new RenderContext();
  
  +++ b/tests/modules/jsonapi_resources_test/src/Resource/FeaturedNodes.php
  @@ -24,18 +25,15 @@ class FeaturedNodes extends EntityResourceBase {
  +      CallableEntityQueryModifier::createFromCallable(function (QueryInterface $query) {
  +        $query->condition('status', NodeInterface::PUBLISHED);
  +        $query->condition('promote', NodeInterface::PROMOTED);
  +      }),
  +      OffsetPaginationEntityQueryModifier::createFromRequest($request),
  +    ]);
  

  I love all of these helpers.

• +++ b/src/EntityQuery/OffsetPaginationEntityQueryModifier.php
  @@ -0,0 +1,61 @@
  +   *   A pagination modifier derived from the request.
  
  +++ b/src/Resource/ResourceBase.php
  @@ -46,4 +48,30 @@ abstract class ResourceBase implements ContainerInjectionInterface {
  +   */
  +  protected function createJsonapiResponse(ResourceObjectData $data, Request $request, $response_code = 200, array $headers = [], LinkCollection $links = NULL, array $meta = []) {
  +    return $this->resourceResponseFactory->create($data, $request, $response_code, $headers, $links, $meta);
  

  And this one!

• +++ b/src/Resource/EntityResourceBase.php
  @@ -38,8 +68,184 @@ abstract class EntityResourceBase extends ResourceBase {
  +  protected function findEntityResourceObjectData($entity_type_id, $entity_query_modifiers = [], $load_latest_revisions = FALSE, $check_access = TRUE) {
  +    $storage = $this->entityTypeManager->getStorage($entity_type_id);
  +    $query = $storage->getQuery();
  ...
  +    $query_cacheability = new CacheableMetadata();
  +    $results = $this->executeQueryInRenderContext(
  +      $query,
  +      $query_cacheability
  +    );
  

  I'd honestly prefer if I just passed in my own entity query that I crafted ahead of time instead of having to pass in modifiers. And then the pagination is just a boolean setting.

  The DX problem we have is definitely ensuring results are executed in a render context.

  If we accepted a query interface (not just entity) we can accept any incoming query (db, search api, etc).

  It also removes the need for entity query modifiers. Which lowers complexity

Search API would need its own helpers, it doesn't share any of the database query interfaces. That dream is dead :P

Also, my fear is that we're going to add additional complexity without exposing proper tools to help developers build with JSON:API instead of putting them into a specific working mindset as the current module does. That's where I think we can be a little more "dangerous" here in this contrib and provide more loose helpers and good examples.

I say we merge this sucker.