close

Filter

loading table of contents...

Headless Server Developer Manual / Version 2301

Table Of Contents

4.13 Remote Links

Overview

The Headless Server is able to retrieve links for content objects like pages, articles or pictures, that are generated by a remote system, like a CAE. These links can be used by a client to link to that remote content.

Remote Links

Figure 4.1. Remote Links


A request is executed from the Headless Server to a configured remote handler in a CAE with a list of content IDs together with optional properties (site, context). The handler generates corresponding links and returns them to the Headless Server.

GraphQL Schema

In the GraphQL schema, the remoteLink property is defined on type CollectionItem:

interface CollectionItem {
  remoteLink(siteId:String, context:String): String
}

All types that inherit from CMLinkable or implement CollectionItem can access this field. For example, the following query retrieves a remote link for an article:

{
  content {
    article(id: "7456") {
      remoteLink
    }
  }
}

The query fragment in the GraphQL schema to retrieve a remoteLink contains the contentId implicitly via the RemoteLinkDataFetcher. Additionally, the following parameters can be set:

siteId

(optional): Defines, for which site the link is generated, as a content can be located in multiple sites.

context

(optional): Defines, for which context the link is generated, as a content can be located in different contexts within a site.

The following example retrieves an article within a site and a specific context:

{
  content {
    article(id: "7456") {
      remoteLink(siteId:"abffe57734feeee", context: "7950")
    }
  }
}

A typical use case is the retrieval of a page content object:

query getPageById($pageId: String!, $siteId: String) {
  content {
    page(id: $pageId) {
      title
      remoteLink(siteId: $siteId)
      pictures {
        title
        remoteLink(siteId: $siteId)
      }
    }
  }
}
Caution

Caution

Please note, that links for commerce objects currently cannot be resolved. For technical reasons it is nonetheless possible to use the remoteLink fragment for commerce object already. A query for remote links for commerce object will always resolve to a null object!

Batch loading mechanism and caching

In order to achieve a reasonable performance when resolving remote links, the Headless Server uses a so called batch loader, which is able to resolve all remote links with only one remote request to the CAE per query level and caches the results (time based eviction).

Configuration

The following configuration options are available, see Section 3.3.4, “Remote Service Adapter Properties” in Deployment Manual for details:

caas.remote.baseurl

Base URL of the remote handler.

caas.remote.httpClientConfig.*

Configuration options of the HttpClient used by the RestTemplate.

caas.cache-specs[remote-links]

(Caffeine Cache) configuration for the remote link cache.

CAE Handler

The CAE UrlHandler handles requests to /internal/service/url and generates links using the CAE link building mechanisms.

As the remote handler for link building is configurable, a custom service can be set up, that handles requests with the given parameters and returns URLs in json format with entities of type UrlServiceResponse.

Deployment

It is assumed that the remote system, that is the CAE, is located in the same trusted network as the Headless Server and so the systems communicate via HTTP. If communication should be established via HTTPS, security configuration needs to be applied to the servers accordingly.

The handler path of the UrlHandler /internal/service/url needs to be configured if required for preview and live environments (for example, traefik, rewrite rules).

Development

For debugging SSL connections, the option caas.remote.httpClientConfig.trustAllSslCertificates can be set to true. This should only be done in a development environment.

Search Results

Table Of Contents
warning

Your Internet Explorer is no longer supported.

Please use Mozilla Firefox, Google Chrome, or Microsoft Edge.