Headless Server Developer Manual / Version 2406.1
Table Of ContentsOverview
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.
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
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.