Resolving references with the delivery endpoint

This page explains how to use the delivery endpoint so that it resolves references to nodes from different workspaces.

The information on this page only applies to the Delivery API.

What is reference resolving?

The endpoints of the delivery API are configured to return content as JSON from one JCR workspace (configured with the workspace property).

Here is a JSON response of a tour from the workspace tours.

{
  "@name": "Kyoto",
  "@path": "/magnolia-travels/Kyoto",
  "@id": "b475f27e-2929-427b-9517-815118a3b36e",
  "@nodeType": "mgnl:content",
  "body": "<p>Experience the still beauty that permeates and surrounds Kyoto. Kyoto is famous for many things, including countless <a href=\"http://www.japan-guide.com/e/e2058.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>temples</u></a>, <a href=\"http://www.japan-guide.com/e/e2059.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>shrines</u></a> and other fascinating historical buildings.</p>\n<p>Join us on a visit to the City of Ten Thousand Shrines. We'll visit Tō-ji, Ginkaku-ji, Kōzan-ji and their remarkable gardens before venturing into the mountains that surround the city. You’ll enjoy a day spent in green Miyama and a day hiking in Shizuhara. You’ll never think about Japan in the same way again.</p> ",
  "name": "Kyoto",
  "description": "The natural side of Japan",
  "destination": [
    "7ec72c48-c33f-418e-b2ff-44cfb4bbb1f2"
  ],
  "location": "Kyoto, Japan",
  "tourTypes": [
    "d2245867-ecaa-4b4e-8743-e0c939be68b7",
    "415025c6-e4b5-4506-9384-34f428a52104"
  ],
  "author": "Magnolia Travels",
  "duration": "7",
  "image": "jcr:44689d29-5966-4d41-8fd4-2dc7da783528",
  "@nodes": []
}

  • Lines 13-15: The tourTypes property contains two references to tour type nodes that reside in the category workspace.

  • Line 19: The image property contains the asset identifier, which is the reference to an asset. In this case the asset is stored in the Magnolia DAM in the dam workspace. In other cases, the asset could be in another asset provider.

We could send additional requests to deliver content for the category and dam workspaces. However, it is more efficient to get the data of the referenced nodes directly with the first request by resolving the references.

In the following sections, we show you how to configure the delivery endpoint in order to resolve the references.

Details concerning the example:

The JSON is requested with this URL: http://localhost:8080/magnoliaAuthor/.rest/tours/magnolia-travels/Kyoto

The basic configuration for the delivery endpoint to read tours in the example so far is:

restEndpoint/tours.yaml

workspace: tours
#references

The references and the referenceResolver properties

The references property is used in info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition for the Delivery API.

Configuration example
references:
  - name: tourTypeReference
    propertyName: tourTypes
    referenceResolver:
      $type: jcrReferenceResolver
      targetWorkspace: category

Properties

references

The references node contains a list of reference definitions.

Specific referencing properties for resolving JCR node references, asset references, or asset links in rich text fields must be defined under the referenceResolver node.

The properties of a single reference are defined in info.magnolia.rest.reference.ReferenceDefinition.

Property Description

name

optional

An arbitrary name. If you do not set the property, the first property must start with a - in order to have proper YAML list item. Using the name property improves the readability of the YAML file.

propertyName

required

The value of this property contains the name of the JCR node property that stores one or multiple references to nodes of other workspaces.

nodeType

optional

The value must be a valid node type. If set, references are resolved only on nodes of the given type.

referenceResolver

required

The reference resolver defines how references are resolved. The properties are defined in info.magnolia.rest.reference.ReferenceResolverDefinition.

     $type

required (unless class is used)

Possible values are:

     class

required (unless $type is used)

The value must refer to a class or interface extending info.magnolia.rest.reference.ReferenceResolverDefinition.

Reference resolver definition classes provided by Magnolia:

  • info.magnolia.rest.reference.jcr.JcrReferenceResolverDefinition

  • info.magnolia.rest.reference.dam.AssetReferenceResolverDefinition

  • info.magnolia.rest.reference.link.RichTextLinkResolverDefinition

Note that these classes may have further properties that must be configured.

When using the jcrReferenceResolver:

  • To control the reference depth of the "root" node, use the referenceDepth property. See also the referenceRepeat property.

  • To control the reference depth in the referenced nodes, use the depthInReferencedNode property.

Where are these configured?

  • referenceDepth and referenceRepeat are root-level properties in an endpoint definition.

  • depthInReferencedNode is defined under the referenceResolver subnode, configured for a named reference under the references (root) node.

Example

/<module-name>/restEndpoints/delivery/my-endpoint.yaml
$type: jcrDeliveryEndpoint_v2
workspace: website
bypassWorkspaceAcls: true
depth: 2
referenceDepth: 2
referenceRepeat: true
nodeTypes:
  - mgnl:page
  - mgnl:contentNode
childNodeTypes:
  - mgnl:area
  - mgnl:component
  - mgnl:contentNode
  - mgnl:page
references:
  - name: referenceToParentWithDefaultDepthInReferencedNode
    propertyName: relatedPage
    referenceResolver:
      class: info.magnolia.rest.reference.jcr.JcrReferenceResolverDefinition
      targetWorkspace: website
  - name: referenceToParentWithDepthInReferencedNodeIs2
    propertyName: relatedPageWithDepth
    referenceResolver:
      class: info.magnolia.rest.reference.jcr.JcrReferenceResolverDefinition
      targetWorkspace: website
      depthInReferencedNode: 2

Resolving JCR node references

Magnolia provides a JCR node reference resolver that is suitable in most cases, with the exception of assets. Use the definition class info.magnolia.rest.reference.jcr.JcrReferenceResolverDefinition for configuration.

Example configuration

restEndpoint/tours.yaml
workspace: tours
references:
  - name: tourTypeReference
    propertyName: tourTypes
    referenceResolver:
      $type: jcrReferenceResolver
      targetWorkspace: category
      expand: true
      generateLink: true

The lines 3-10 define how the references stored in the field tourTypes are resolved.

{
    "@name": "Kyoto",
    "@path": "/magnolia-travels/Kyoto",
    "@id": "b475f27e-2929-427b-9517-815118a3b36e",
    "@nodeType": "mgnl:content",
    "body": "<p>Experience the still beauty that permeates and surrounds Kyoto. Kyoto is famous for many things, including countless <a href=\"http://www.japan-guide.com/e/e2058.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>temples</u></a>, <a href=\"http://www.japan-guide.com/e/e2059.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>shrines</u></a> and other fascinating historical buildings.</p>\n<p>Join us on a visit to the City of Ten Thousand Shrines. We'll visit Tō-ji, Ginkaku-ji, Kōzan-ji and their remarkable gardens before venturing into the mountains that surround the city. You’ll enjoy a day spent in green Miyama and a day hiking in Shizuhara. You’ll never think about Japan in the same way again.</p> ",
    "name": "Kyoto",
    "description": "The natural side of Japan",
    "destination": [
        "7ec72c48-c33f-418e-b2ff-44cfb4bbb1f2"
    ],
    "location": "Kyoto, Japan",
    "tourTypes": [
        {
            "@name": "ecotourism",
            "@path": "/tour-types/ecotourism",
            "@id": "d2245867-ecaa-4b4e-8743-e0c939be68b7",
            "@nodeType": "mgnl:category",
            "body": "Nature is calling you. And there’s nowhere more natural than Africa’s savannah plains or the icy wilderness of Antartica. But what’s even better than getting closer to nature is knowing that when you travel with us, you’re making your own contribution to keeping those untouched parts of earth just as they are.",
            "name": "ecotourism",
            "level": "level-1",
            "description": "Call of the wild",
            "icon": "jcr:8ad908e7-2ab7-4fe2-b1ed-e6eb3f68f3b0",
            "displayName": "Ecotourism, Nature & Wildlife",
            "image": "jcr:2fd89d97-f932-4533-8a30-d70988bde30c",
            "@link": "/magnoliaAuthor/tour-types/ecotourism.html",
            "@nodes": [
            ]
        },
        {
            "@name": "offPath",
            "@path": "/tour-types/offPath",
            "@id": "415025c6-e4b5-4506-9384-34f428a52104",
            "@nodeType": "mgnl:category",
            "body": "Riding on a big tour bus, eating tourist menus and taking pictures of the Eiffel Tower is not your idea of travelling. You want to find something new, and see things from a local point of view. With us, you can discover the local gems that most travellers never experience. ",
            "name": "offPath",
            "level": "level-1",
            "description": "Unique holidays that take you off the beaten track ",
            "icon": "jcr:6d5d576a-79f9-48d9-b141-6682f2eef585",
            "displayName": "Off the Beaten Path",
            "image": "jcr:272f75b9-ed87-4e0b-8bf3-15db217ba897",
            "@link": "/magnoliaAuthor/tour-types/offPath.html",
            "@nodes": [
            ]
        }
    ],
    "author": "Magnolia Travels",
    "duration": "7",
    "image": "jcr:44689d29-5966-4d41-8fd4-2dc7da783528",
    "@nodes": [
    ]
}

Properties

Property Description

referenceResolver

required node

     $type

required (unless class is used)

Must be jcrReferenceResolver.

     class

required (unless $type is used)

Must be info.magnolia.rest.reference.jcr.JcrReferenceResolverDefinition or a subclass.

     targetWorkspace

required

The name of the workspace containing the nodes that are referenced.

     expand

optional, default is true

If set to true, all properties of the referenced node are included in the JSON.

If false, the JSON contains only links to the referenced node. See generateLink below.

     generateLink

optional, default is false

If true, the resolved node contains an additional link property. The value of the link property is a relative link to directly render the referenced node.

The format of the generated links depends on the configuration of the link generator (configured in config workspace at /server/rendering/linkManagement).

     depthInReferencedNode

optional, default is -1

Sets the depth in the referenced nodes.

The default value of -1 means that the endpoint returns the referenced nodes up to the configured referenceDepth property (a specific depth for the returned "root" nodes) but it also returns all their children.

Depth in the referenced nodes

While the referenceDepth property sets a specific depth for the returned "root" nodes, you can control the depth in the referenced nodes with the depthInReferencedNode property.

Example: Depth in the referenced nodes in the Tour Finder page

In the Travel Demo, the Tour Finder page has the following structure:

http://localhost:8080/magnoliaAuthor/.magnolia/admincentral#app:jcr-browser-app:browser;/travel/tour-finder

Structure of the Tour Finder page

Consider these three configuration cases:

  1. You don’t configure a resolver at all. In this case, for the tour-finder node, you would only receive:

    ...
"tourFinder": "d25e69d9-27d0-4477-824c-7cc0714c97ce"
...

  2. You do configure a resolver in your endpoint, but only set 1 as the value of the depthInReferencedNode property in it:

    references:
  - name: referenceToParentWithDefaultDepthInReferencedNode
    propertyName: tourFinder
    referenceResolver:
      $type: jcrReferenceResolver
      targetWorkspace: website
      depthInReferencedNode: 1

    In this case, the tourFinder node is resolved and shows its content, but only to one level. The main and footer area nodes are not resolved any further:

    ...
      "tourFinder": {
        "@name": "tour-finder",
        "@path": "/travel/tour-finder",
        "@id": "d25e69d9-27d0-4477-824c-7cc0714c97ce",
        "@nodeType": "mgnl:page",
        "hideInNav": true,
        "title": "Tour Finder",
        "main": {
          "@name": "main",
          "@path": "/travel/tour-finder/main",
          "@id": "9cafcc1e-e561-4f15-83ba-6019c8107a86",
          "@nodeType": "mgnl:area",
          "@nodes": []
        },
        "footer": {
          "@name": "footer",
          "@path": "/travel/tour-finder/footer",
          "@id": "ce31ad28-22b2-4c94-9bff-515ee7883634",
          "@nodeType": "mgnl:area",
          "@nodes": []
        },
        "@nodes": [
          "main",
          "footer"
        ]
      }
...

  3. You set 2 for the depthInReferencedNode property in the reference resolver:

    references:
  - name: referenceToParentWithDefaultDepthInReferencedNode
    propertyName: tourFinder
    referenceResolver:
      $type: jcrReferenceResolver
      targetWorkspace: website
      depthInReferencedNode: 2

    In this case, even the main and footer area nodes are resolved:

    ...
      "tourFinder": {
        "@name": "tour-finder",
        "@path": "/travel/tour-finder",
        "@id": "d25e69d9-27d0-4477-824c-7cc0714c97ce",
        "@nodeType": "mgnl:page",
        "hideInNav": true,
        "title": "Tour Finder",
        "main": {
          "@name": "main",
          "@path": "/travel/tour-finder/main",
          "@id": "9cafcc1e-e561-4f15-83ba-6019c8107a86",
          "@nodeType": "mgnl:area",
          "0": {
            "@name": "0",
            "@path": "/travel/tour-finder/main/0",
            "@id": "506bfd9a-ef9f-42bf-8650-f32a3b2fd841",
            "@nodeType": "mgnl:component",
            "@nodes": []
          },
          "@nodes": [
            "0"
          ]
        },
        "footer": {
          "@name": "footer",
          "@path": "/travel/tour-finder/footer",
          "@id": "ce31ad28-22b2-4c94-9bff-515ee7883634",
          "@nodeType": "mgnl:area",
          "footer1": {
            "@name": "footer1",
            "@path": "/travel/tour-finder/footer/footer1",
            "@id": "76c936d5-c305-4745-8e23-cfb694692bad",
            "@nodeType": "mgnl:area",
            "@nodes": []
          },
          "footer2": {
            "@name": "footer2",
            "@path": "/travel/tour-finder/footer/footer2",
            "@id": "a2d47f9d-eddf-493e-bf83-e7a64c7be2f0",
            "@nodeType": "mgnl:area",
            "@nodes": []
          },
...

Reference conflicts

You may have a situation where resolvers reference fields with an identical name because the fields are generated by a jcrMultiField of different pages.

You can resolve this conflict by setting a different name for one of the fields through the name property in the configuration of the field. In the following example, a custom name: categoryField is configured for a jcrMultiField:

    categories:
      $type: jcrMultiField
      field:
        name: categoryField
        $type: linkField
        required: true
        datasource:
          $type: jcrDatasource
          workspace: category
          rootPath: /
          allowedNodeTypes:
            - mgnl:folder
            - mgnl:category

Resolving asset references

Magnolia REST modules come with an asset resolver, which creates a (relative) link to the image as well as Dublin Core metadata (if it exists for the asset). Use the info.magnolia.rest.reference.dam.AssetReferenceResolverDefinition class for configuration.

The Magnolia asset resolver operates on the DAM API.

If the referenced assets reside in the Magnolia DAM, the asset resolver can also generate links to asset renditions (also known as image variations). Renditions must be defined in the theme that is linked to the site definition. See image variations to learn how to define asset renditions in a theme.

For image variations to be resolved correctly, make sure that the fallback site has theme variations configured or extends a site definition with desired variations.

Example configuration

This example is based on the basic configuration shown above.

restEndpoint/tours.yaml

workspace: tours

references:
  - name: tourImageReference
    propertyName: image
    referenceResolver:
      $type: assetReferenceResolver
      assetRenditions:
        - 320x240
        - 1600x1200
        - nonexistent

The lines 5-12 define how the references stored in the dam workspace are resolved.

{
    "@name": "Kyoto",
    "@path": "/magnolia-travels/Kyoto",
    "@id": "b475f27e-2929-427b-9517-815118a3b36e",
    "@nodeType": "mgnl:content",
    "body": "<p>Experience the still beauty that permeates and surrounds Kyoto. Kyoto is famous for many things, including countless <a href=\"http://www.japan-guide.com/e/e2058.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>temples</u></a>, <a href=\"http://www.japan-guide.com/e/e2059.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>shrines</u></a> and other fascinating historical buildings.</p>\n<p>Join us on a visit to the City of Ten Thousand Shrines. We'll visit Tō-ji, Ginkaku-ji, Kōzan-ji and their remarkable gardens before venturing into the mountains that surround the city. You’ll enjoy a day spent in green Miyama and a day hiking in Shizuhara. You’ll never think about Japan in the same way again.</p> ",
    "name": "Kyoto",
    "description": "The natural side of Japan",
    "destination": [
        "7ec72c48-c33f-418e-b2ff-44cfb4bbb1f2"
    ],
    "location": "Kyoto, Japan",
    "tourTypes": [
        "d2245867-ecaa-4b4e-8743-e0c939be68b7",
        "415025c6-e4b5-4506-9384-34f428a52104"
    ],
    "author": "Magnolia Travels",
    "duration": "7",
    "image": {
        "@name": "flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg",
        "@path": "/tours/flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg",
        "@id": "jcr:44689d29-5966-4d41-8fd4-2dc7da783528",
        "@link": "/magnoliaAuthor/dam/jcr:44689d29-5966-4d41-8fd4-2dc7da783528/flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg",
        "metadata": {
            "fileName": "flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg",
            "mimeType": "image/jpeg",
            "caption": "Stairs to Ōminesan-ji temple",
            "fileSize": "1115288",
            "height": "2133",
            "width": "1600",
            "title": "Stairs to Ōminesan-ji temple",
            "format": "image/jpeg",
            "coverage": "Yoshino district, Nara prefecture, Japan",
            "description": "Ōminesan-ji (大峯山寺 Ōminesan-ji) is an important temple of the Shugendō religion in Yoshino district, Nara prefecture, Japan. It is located at the peak of Mount Ōmine, or Sanjōgatake. According to tradition, it was founded by En no Ozunu, the founder of Shugendō, a form of mountain asceticism drawing from Buddhist and Shinto beliefs.",
            "publisher": "Tim Notari",
            "rights": "by-sa/2.0/",
            "source": "https://www.flickr.com/photos/tasteful_tn/204886404/",
            "creator": [
                "superuser"
            ],
            "contributor": [
                "Tim Notari"
            ],
            "subject": [
                "Ōminesan-ji temple"
            ],
            "date": "2019-01-17T10:30:29.618+01:00",
            "created": "2015-01-29T08:45:41.613+01:00",
            "modified": "2019-01-17T10:30:29.618+01:00"
        },
        "renditions": {
            "320x240": {
                "mimeType": "image/jpeg",
                "link": "/magnoliaAuthor/.imaging/mte/travel-demo-theme/320x240/dam/tours/flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg/jcr:content/flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg"
            },
            "1600x1200": {
                "mimeType": "image/jpeg",
                "link": "/magnoliaAuthor/.imaging/mte/travel-demo-theme/1600x1200/dam/tours/flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg/jcr:content/flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg"
            },
            "nonexistent": {
                "mimeType": "image/jpeg",
                "link": "/magnoliaAuthor/.imaging/default/dam/tours/flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg/jcr:content.jpg"
            }
        }
    },
    "@nodes": [
    ]
}

NOTE:

  • Line 23: The property @link provides a relative link to the asset. The asset is served by info.magnolia.dam.core.download.DamDownloadServlet.

  • Line 51 pp - renditions. When requesting the links of the renditions, they are served by info.magnolia.imaging.ImagingServlet.

    • Line 54: The link contains a relative link to an asset rendition (of a defined image variation).

    • Line 62: The link to an undefined rendition returns the original uploaded asset. Here it returns as @link of line 51 (the former served by dam servlet, the latter served by imaging servlet).

Properties

Property Description

referenceResolver

required node

     $type

required (unless class is used)

Must be assetReferenceResolver.

     class

required (unless $type is used)

Must be info.magnolia.rest.reference.dam.AssetReferenceResolverDefinition or a subclass.

     expand

optional, default is true

If set to false, neither the list of defined renditions nor the meta data is shown.

If includeDownloadLink is set to true, a link is returned, otherwise the asset item key or original text is shown.

     includeDownloadLink

optional, default is true

If set to false, the JSON file does not show the relative asset link.

     includeAssetMetadata

optional, default is true

If set to false, metadata is not included.

     assetRenditions

optional

A list of rendition names as defined in the theme linked to the current site.

         <rendition-name>

required

A rendition name.

To get the asset in its original (default) size, use original as the value.

If you add an undefined (a non-existent) rendition, the asset resolver creates a link to the default variation which is the same as the asset in its original size.

Resolving asset links in rich text fields

We provide a resolver which helps resolve links for assets in the rich text field. In the following example, the first word Kyoto in the rich text field has been turned into a link to the kyoto.png image with UUID 0a3bb34f-b49f-4e02-a9e9-e46cf860b612:

Rich text field

In the repository, this part of content is stored like this:

Content stored in the repository

Without the asset link resolver, the endpoint returns what is stored in the repository, with escaped double quotes:

<p>Experience the still beauty that permeates and surrounds
<a href=\"${link:{uuid:{0a3bb34f-b49f-4e02-a9e9-e46cf860b612},repository:{dam},path:{/untitled}}}\">Kyoto</a>.
 Kyoto is famous for many things,

If the resolver is set, the link to the asset will be resolved as a URL:

<p>Experience the still beauty that permeates and surrounds
<a href=\"http://localhost:8080/magnoliaAuthor/fallback/dam/jcr:0a3bb34f-b49f-4e02-a9e9-e46cf860b612/kyoto.jpg\">Kyoto</a>.
 Kyoto is famous for many things,

Properties

Property Description

referenceResolver

required node

     $type

required (unless class is used)

Must be richTextLinkReferenceResolver.

     class

required (unless $type is used)

Must be info.magnolia.rest.reference.link.RichTextLinkResolverDefinition or a subclass.

     completeUrl

optional, default is true

The endpoint returns a full URL, using the value configured in server.defaultBaseUrl (see Configuration management).

If set to false, a relative link is returned instead, for example:

<p>Experience the still beauty that permeates and surrounds
 <a href=\"/magnoliaAuthor/dam/jcr:0a3bb34f-b49f-4e02-a9e9-e46cf860b612/kyoto.jpg\">Kyoto</a>.
 Kyoto is famous for many things,

Example configuration

workspace: website

references:
  - name: referenceWithRichText
    propertyName: content
    referenceResolver:
      $type: richTextLinkReferenceResolver
      completeUrl: false
Related topics
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules