If you don’t have Magnolia installed and running, go to the page called Installing Magnolia through npm CLI and complete the steps described there.
The declarative-rest-demo light module.
You can get a copy of the light module by cloning the https://git.magnolia-cms.com/projects/MODULES/repos/rest-client/ repository and extracting the declarative-rest-demo directory to the folder defined by the magnolia.resources.dir property. If you installed Magnolia using CLI, it is the light-modules folder, located in the root of your Magnolia installation:
In this case, a REST client is configured to send a request to the /countries path of the https://placesapi.dev/api/v1/ endpoint to get a list of countries:
Client configuration
The client is called countries, its name is derived from the configuration file’s name. The REST call is named allCountries in this definition.
If the REST API service needs an authentication of a REST call, you can configure a security (authentication) scheme for it under the securitySchemes
node. You can use scheme types basic and bearer, which are available out of the box in the REST client module.
Example configuration of a client called bearer-security utilizing the bearer security scheme and an expiration limit. The scheme’s configuration is defined under the bearerTokenWithExpiryDuration node, the authentication call is configured under authenticateWithDurationAsLong.
OAuth2 bearer security scheme with expiry duration
Example configuration of a client called knowledgeSource also utilizing the bearer security scheme and an expiration limit. The scheme’s configuration is defined under the oauth2 node. The authentication call is configured under authenticate in a separate knowledgeSourceAuth.yaml configuration file.
This example showcases a situation in which you are using a third-party authentication service for your REST calls. In other words, the authentication URL is different from the service URL.
In this particular example configuration, the domain where the token is served from is example.net while the REST service is hosted on example.com.
This case makes use of a REST client called books and a JavaScript model called search. The model invokes the configured searchByIsbn call that queries the https://openlibrary.org/dev/docs/api/read API with a request for a record of a book identified by the ISBN 13 number.
The component template script then renders the book’s title, number of pages and its cover image (if available).
var BookModel = function () {
var restClient = restClientFactory.createClientIfAbsent(restClientRegistry.getProvider("books").get());
this.search = function (isbn) {
var result = restClient.invoke("searchByIsbn", { isbn: isbn});
var data = JSON.parse(result.getEntity());
if (data && data.records) {
var keys = Object.keys(data.records);
return data.records[keys[0]].data;
}
returnnull;
}
};
new BookModel();Copy
Case 4: Configuration using an OpenAPI schema
The benefit of a configuration using an OpenAPI schema is that all that is required to configure a REST client is reduced just to two properties, class and schemaUrl.
For the class, you use info.magnolia.openapi.client.OpenApiRestClientDefinition.
For the schemaUrl, you provide a link to an existing definition (file or URL) complying with the OpenAPi v3 specification.
[#assign aDateTime = .now]
[#assign results = restfn.call("wikipedia", "onThisDay", {"type":"all", "mm":aDateTime?string["MM"], "dd":aDateTime?string["dd"]}) ] (1)
<h2>What happened on ${aDateTime?string["MMMM"]} ${aDateTime?string["dd"]} in the past?</h2>
[#list results.get("selected").elements() as event]
<p>
${event.get("text").textValue()} (${event.get("year").intValue()?c}) (2)
</p>
[/#list]
<p>(Source: en.wikipedia.org)</p>Copy
1
The alias onThisDay is used to target the endpoint path since the alias is defined in the schema. If this weren’t the case, you can always refer to a call name using the following pattern: method:/path/pathAction.
2
At the end of the directive, the c FreeMarker builtin is used to render the intValue() for the year without formatting for human audience, for example as 2019 rather than 2,019.
After passing the template values for type, month and date, the component displays a list of notable events that happened on the given day at some point in the past, for example: