restfn

FreeMarker development only

restfn templating functions give access to REST clients configured with the REST Client module.

accessing 3rd party systems with REST

Using Magnolia REST clients with restfn in FTL template scripts could slow or even block the rendering of the scripts, because the call is synchronous and waits till the request returns. Before an actual implementation, always consider at least the following:

  • The reliability of the endpoint.

  • Implementing restfn in an asynchronous way via a client side request.

  • Accessing the endpoint directly with client side code.

  • How any of your page caching configurations will affect content delivered from restfn.

Call response

Invokes a call for a full response to a configured REST client, with optional assignment of custom template values for request parameters or body, and with optional specific error handler.

Returns a full response as a map of clients and call names, with error handlers and/or custom template values, if available.

Method signature

Response callForResponse(String restClientName, String restCallName, Map<String, Object> customValues, RestClientExceptionHandler errorHandler)

Arguments

Argument Description

restClientName

required

Name of a configured client.

restCallName

required

Name of a configured call.

See also below the form of the REST call name.

customValues

optional

A map of custom values passed to the endpoint with the call.

errorHandler

optional

Specification of a handler for errors, for example {"code": 404}.

Usage

restfn.callForResponse(restClientName, restCallName, customValues, errorHandler)

Call client

Invokes a call to a configured REST client with optional assignment of custom template values for request parameters or body.

Returns an object. The actual type of the returned object conforms with the entityClass configured for the REST call.

Method signature

Object call(String restClientName, String restCallName, Map<String, Object> customValues)

Arguments

Argument Description

restClientName

required

Name of a configured client.

restCallName

required

Name of a configured call.

See also below the form of the REST call name.

customValues

optional

A map of custom values passed to the endpoint with the call.

Usage

restfn.call(restClientName, restCallName, customValues)

[#assign firstPost = restfn.call("restfn-posts", "single")]

[#-- with a custom value --]
[#assign customValues = {"id":"2"} /]
[#assign secondPost = restfn.call("restfn-posts", "single", customValues) /]

Example with custom values

Client definition:

/my-light-module/restClients/fooClient-restfn.yaml
baseUrl: http://localhost:8081
restCalls:
  random:
    method: post
    body: {"name": "{name}", "email": "{email}"}
    entityClass: com.fasterxml.jackson.databind.JsonNode
    responseContentType: application/json
    path: /alumni
    headers:
      Content-Type: "application/json; charset=UTF-8"

Page template definition and script:

/my-light-module/templates/pages/myPage_restfn.yaml
title: My Home Page
templateScript: /my-light-module/templates/pages/myPage_restfn.ftl
renderType: freemarker
visible: true
/my-light-module/templates/pages/myPage_restfn.ftl
<!doctype html>
<html lang="${cmsfn.language()}">

<head>
    [@cms.page /]
    <meta charset="utf-8">
</head>

[#assign customValues = {"name": "JohnDoe", "email": "johndoe@example.com"} /]
[#assign post = restfn.call("fooClient-restfn", "random", customValues) /]

<h1>${post}</h1>

<body>
    <h1>Hello, world!</h1>
</body>

</html>

The return type of restfn depends on the entityClass configured for the respective REST call. If the entityClass returns a JSON node com.fasterxml.jackson.databind.JsonNode, see Client configuration and Component template script for more information.

The form of the restCallName

By default, the name is mapped to this pattern: method:/path/pathAction. An operationId, a unique string used to identify the operation in the OpenAPI specification, is an optional alias for the call name.

In the following configuration snippet, an operationId has been set to findByStatus:

paths:
  /pet/findByStatus:
    get:
      operationId: findByStatus

You could then invoke the call using not only

restfn.invoke("get:/pet/findByStatus", "available")

but also with

 restfn.invoke("findByStatus", "available")

Get proxy implementation

Obtains a client proxy implementation for a given client and configured proxy class.

Returns an object mapping each client to its proxy.

Method signature

Object getProxy(String restClientName, String proxyClassName)

Arguments

Argument Description

restClientName

required

Name of a configured client.

proxyClassName

required

Name of a proxy class.

Usage

restfn.getProxy(restClientName, proxyClassName)

Call proxy

Invokes a method on a proxy with given parameters.

Returns a result according to the return type of the method called.

Method signature

Object call(Object proxy, String methodName, Object…​ args)

Arguments

Argument Description

proxy

required

Instance of a declared proxy.

methodName

required

Name of the method of the proxy.

args

required

A varargs parameter. In FreeMarker context, just pass an array of arguments.

Usage

restfn.call(proxy, methodName, args)

Call client with a proxy implementation

Invokes a method on a client with a specified proxy implementation and with given parameters.

Returns a result according to the return type of the method called.

Method signature

Object call(String restClientName, String proxyClass, String methodName, Object…​ args)

Arguments

Argument Description

restClientName

required

Name of a configured client.

proxyClass

required

Name of a proxy class.

methodName

required

Name of the method.

args

required

A varargs parameter. In FreeMarker context, just pass an array of arguments.

Usage

restfn.call(restClientName, proxyClass, methodName, args)

Convert JsonNode to Map

Converts a JsonNode object to a hash map. Use either this or the asList() function depending on what type of JSON the API your query returns.

Returns a hash map.

Method signature

Map<String, Object> asMap(jsonNode)

Arguments

Argument Description

jsonNode

required

Variable of type com.fasterxml.jackson.databind.JsonNode.

Usage

restfn.asMap(jsonNode)

[#assign colombia = restfn.asMap(restfn.call("countries", "colombia"))]

[#-- Note: Provided the restfn.call("countries", "colombia") is defined
using the com.fasterxml.jackson.databind.JsonNode entity class.--]

Convert JsonNode to List

Converts a JsonNode object to an array list. Use either this or the asMap() function depending on what type of JSON the API your query returns.

Returns an array list.

Method signature

List<Object> asList(jsonNode)

Arguments

Argument Description

jsonNode

required

Variable of type com.fasterxml.jackson.databind.JsonNode.

Usage

restfn.asList(jsonNode)

[#assign countriesList = restfn.asList(restfn.call("countries", "allCountriesArray"))]

[#-- Note: Provided the restfn.call("countries", "allCountriesArray") is defined
using the com.fasterxml.jackson.databind.JsonNode entity class.--]
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