Page tree
Skip to end of metadata
Go to start of metadata

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

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 client

This method executes a call to a configured REST client, with optional assignment of custom values.

Method signature

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

Arguments

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.

Returns

An object. The actual type of the returned object conforms with the entityClass configured for the REST 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)  /]

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. For example, 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 service

Retrieves an instance of a declared service interface. The instance is created by the configured client factory.

Method signature

Object getService(String restClientName, String restClientServiceClass)

Arguments

restClientName

required

Name of a configured client.

restClientServiceClass

required

Fully qualified class name of a declared service interface for the client.

Returns

An object.

Usage

restfn.getService(restClientName, restClientServiceClass )

[#assign jokesService = restfn.getService("icndbClient", "info.magnolia.documentation.modules.restclientexamples.client.IcndbService")]

Call service (with service object)

This restfn method executes a method of a declared service interface and returns an object according to the return type of the interface method called.

Method signature

Object call(Object service, String methodName, Object... args)

Arguments

service

required

Instance of a declared service. Can be obtained by the #getService method.

methodName

required

Name of the method of the service interface.

args

required

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

Returns

An object. The actual type of the returned object is defined in the service interface method. For example, if the service interface method defines the return type as a JSON object, then that's what you get.

Usage

restfn.call(service, methodName, args)

[#assign jokesService = restfn.getService("icndbClient", "info.magnolia.documentation.modules.restclientexamples.client.IcndbService")]
[#assign params = ["random", "John", "Doe"] /]
[#assign response = restfn.call(jokesService, "joke", params)  /]

[#-- another option: pass the args in brackets: --]
[#assign response = restfn.call(jokesService, "joke", ["random", "Tiger", "Lilly"] )  /]

Call service (with service interface name)

This function also executes a method of a declared service interface and returns an object according to the return type of the interface method called, however with different input parameters.

Method signature

Object call(String restClientName, String restClientServiceClass, String methodName, Object... args)

Arguments

restClientName

required

Name of a configured client.

restClientServiceClass

required

Fully qualified class name of a declared service interface for the client.

methodName

required

Name of the method of the service interface.

args

required

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

Returns

An object. The actual type of the returned object conforms with the return type of the method of a declared service interface.

Usage

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


[#assign params = ["random", "John", "Doe"] /]
[#assign response = restfn.call( "icndbClient",  "info.magnolia.documentation.modules.restclientexamples.client.IcndbService",  "joke", params)  /]

[#-- another option: pass the args in brackets: --]
[#assign response = restfn.call( "icndbClient",  "info.magnolia.documentation.modules.restclientexamples.client.IcndbService",  "joke", ["random", "Lisa", "Klein"])  /]

Convert JsonNode to Map

This function 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.

Method signature

Map<String, Object> asMap(jsonNode)

Arguments

jsonNode

required

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

Returns

A hash map.

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

This function 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.

Method signature

List<Object> asList(jsonNode)

Arguments

jsonNode

required

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

Returns

An array list.

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