[PP-1] Define a JSON API link relation for entities

Since the ability to do $entity->toUrl('jsonapi') also requires a entity.$entity_type_id.jsonapi route to exist, we'll need to take inspiration from #2293697: EntityResource POST routes all use the confusing default: use entity types' https://www.drupal.org/link-relations/create link template if available too.

Here's a rough initial version.

1. +++ b/jsonapi.module
   @@ -33,6 +33,19 @@ function jsonapi_help($route_name, RouteMatchInterface $route_match) {
   +    $jsonapi_path = $entity_type->getBundleEntityType()
   +      ? sprintf('/jsonapi/%s/{%s}/{%s}', $entity_type->id(), $entity_type->getBundleEntityType(), $entity_type->id())
   +      : sprintf('/jsonapi/%s/%s/{%s}', $entity_type->id(), $entity_type->id(), $entity_type->id());
   

   This is correct.

2. +++ b/src/Routing/Routes.php
   @@ -139,6 +139,9 @@ class Routes implements ContainerInjectionInterface {
   +      // Enable generating this URL by doing $entity->toUrl('jsonapi').
   +      // @see jsonapi.link_relation_types.yml
   +      $collection->add(sprintf('entity.%s.jsonapi', $resource_type->getEntityTypeId()), $route_individual);
   

   But this is not yet correct. Because a separate individual route is generated for each bundle of an entity type, this currently is using the last enumerated bundle and hardcoding that for all entities of this entity type.

   For example, for Node on a default install this will result in /jsonapi/node/page/<node ID> for all nodes, which is obviously wrong.

   IOW: this needs a different route definition.

Note that this is already resulting in <link rel="jsonapi" href="/jsonapi/node/page/1" /> automatically being added to the HTML <head>, as well as a Link:</jsonapi/node/page/1>; rel="jsonapi" response header!

#7: no, that's the entity type ID, not the entity ID!

#8: Perhaps. What are the link relation names you suggest?

1. jsonapi-individual
2. jsonapi-collection
3. jsonapi-relationship
4. jsonapi-related

but… jsonapi-relationship and jsonapi-related links don't entirely make sense, because you'd need to add a URL for every related/relationship thing for that entity type + bundle! And that's something that Entity::toUrl() simply does not support: it hardcodes the assumption that for every relationship there is only one URL.

Therefore only jsonapi-individual and jsonapi-collection are ever possible. Which means that we might as well simplify it to jsonapi and jsonapi-collection.

but… jsonapi-relationship and jsonapi-related links don't entirely make sense, because you'd need to add a URL for every related/relationship thing for that entity type + bundle! And that's something that Entity::toUrl() simply does not support: it hardcodes the assumption that for every relationship there is only one URL.

I'm wondering whether it should be possible to pass along some of the parameters using the $options parameter, if well, its optional.

#10: I thought about that too, but that'd be violating the API, because:

  /**
   * Gets the URL object for the entity.
   *
   * The entity must have an id already. Content entities usually get their IDs
   * by saving them.
   *
   * URI templates might be set in the links array in an annotation, for
   * example:
   * @code
   * links = {
   *   "canonical" = "/node/{node}",
   *   "edit-form" = "/node/{node}/edit",
   *   "version-history" = "/node/{node}/revisions"
   * }
   * @endcode
   * or specified in a callback function set like:
   * @code
   * uri_callback = "comment_uri",
   * @endcode
   * If the path is not set in the links array, the uri_callback function is
   * used for setting the path. If this does not exist and the link relationship
   * type is canonical, the path is set using the default template:
   * entity/entityType/id.
   *
   * @param string $rel
   *   The link relationship type, for example: canonical or edit-form.
   * @param array $options
   *   See \Drupal\Core\Routing\UrlGeneratorInterface::generateFromRoute() for
   *   the available options.
   *
   * @return \Drupal\Core\Url
   *   The URL object.
   *
   * @throws \Drupal\Core\Entity\EntityMalformedException
   * @throws \Drupal\Core\Entity\Exception\UndefinedLinkTemplateException
   */
  public function toUrl($rel = 'canonical', array $options = []);

I just stumbled upon the issue that aims to make it possible to have link relationships have multiple URLs: #2801067 — I left a comment there about this issue: #2801067-4: Link templates on entity types should support multiple links.

Anything new in core land that can help us?

No.

In #9, I wrote:

Therefore only jsonapi-individual and jsonapi-collection are ever possible. Which means that we might as well simplify it to jsonapi and jsonapi-collection.

But the only link relationship that really matters is the individual JSON API resource. Because that is what allows the /node/1 HTML response to automatically have a

Link:</jsonapi/node/article/UUID>; rel="jsonapi"

link relationship in the response header, and from there, all other links can be followed. That's enough.

Updated patch attached, should be green.

+++ b/tests/src/Functional/JsonApiFunctionalTest.php
@@ -20,6 +20,11 @@ class JsonApiFunctionalTest extends JsonApiFunctionalTestBase {
+    // 0. Discoverability: verify
+    $this->drupalGet('/user/1');
+    var_dump($this->drupalGetHeader('Link'));
+    return;

I was working on integration test coverage. I didn't mean to add that to this patch.

This doesn't work yet, because #2878463: [PP-1] Define a JSON API link relation for entities is a hard blocker.

I think the link in #17 should have been #2282029: Automate link relationship headers for all entity types, not just nodes, but I'm not sure.

I don't see why we couldn't test against only Node for now, then this wouldn't need to be blocked AFAICT.

Let's get this going again.

1. #2936714: Entity type definitions cannot be set as 'internal' means we should only add the jsonapi link template on non-internal entity types. Updated jsonapi_entity_type_alter() accordingly.
2. Because #2940336: JSON API incorrectly requires the "access content" permission for *all* routes is not yet fixed, I had to grant the access content permission to be able to write an integration test.
3. … this works kind of when manually testing as an authenticated user, but then it results in Link:</jsonapi/node/page/435>; rel="jsonapi", i.e. with the node ID rather than the node UUID.
4. … this fails when testing as an anonymous user, because then $url->access($this->currentUser) is called, which results in the route being constructed, but that fails because the provided parameter is the node ID, which \Drupal\jsonapi\ParamConverter\EntityUuidConverter::convert() doesn't know how to convert, nor does it want to. The problem, in other words, is the {node} route parameter that is firmly associated with the ID, not the UUID. We need something like {node:uuid}. That'd also solve the problem described in the previous bullet.

I think we might need a routing system expert for this.

There is a similar core issue for 4. isn't it? (#2353611: Make it possible to link to an entity by UUID). It wouldn't work in the current state, but we could check for something like node:uuid or so instead. I suggested a small change of direction for that issue, so we can maybe make more progress over there.

Yep, I was contemplating linking to that issue, but didn't have the time to dig into the status/scope of #2353611, so thank you for doing that! ❤️

Let's make it clear that this is hard-blocked on #2353611. Posted #2353611-191: Make it possible to link to an entity by UUID to make that clear in the blocking issue too.

2.x will require >=8.5. Hence 1.x will never be able to do this.