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.

Resolving JCR references
Resolving asset references
Resolving asset links in rich text fields

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

To control the reference depth, see also the referenceDepth and referenceRepeat properties.

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.

Configuration properties

See referenceResolver properties for resolving JCR node references.

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": [
    ]
}

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.

Configuration properties

See referenceResolver properties for resolving asset references.

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).

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,

Configuration properties

See referenceResolver properties for resolving asset links in rich text fields.

Example configuration

restEndpoints/tours_v1.yaml

workspace: tours

references:
  - name: referenceWithRichText
    propertyName: body
    referenceResolver:
      $type: richTextLinkReferenceResolver

Magnolia 6.3 beta

Magnolia 6.3 is in beta. We are updating docs based on development and feedback. Consider the 6.3 docs currently in a state of progress and not final.

We are working on some 6.3-beta known issues during this phase.

Resolving references with the delivery endpoint

What is reference resolving?

The references and the referenceResolver properties

Resolving JCR node references

Configuration properties

Example configuration

Reference conflicts

Resolving asset references

Configuration properties

Example configuration

Resolving asset links in rich text fields

Configuration properties

Example configuration

Location

Main doc sections

Magnolia 6.3 beta

The `references` and the `referenceResolver` properties