-
Jorge FrancoSenior Software Engineer, Magnolia
Integrating Content through Declarative REST Clients
Magnolia offers connector packs to easily integrate various third-party systems such as Commerce, Digital Asset Management (DAM), and Analytics platforms. For integrations beyond our connector packs, we offer Multisource, an uber-useful feature that lets you integrate Magnolia with any system that has a REST API. Multisource also provides a UI framework for displaying content to authors in the AdminCentral, overcoming the challenge of managing siloed content.
Setting up a REST client with Multisource
You can customize Magnolia using our unique Light Development. It allows you to expand Magnolia’s capabilities through YAML files without writing a single line of Java code. With each YAML configuration file in the restClients folder in your light module, you create a declarative REST client.
In the same way, you can configure any external sources of content in Magnolia and use their content on your pages and in your applications. You can find more information in the documentation.
Compatible content sources
By default, our REST clients use the RestEASY implementation of the Jakarta RESTful Web Services (JAX-RS), supporting a vast amount of content sources that can be defined in two ways.
The first definition type is using the OpenAPI specification. The configuration includes the Java class and the URL that defines the REST API. This is the preferred way because the definition is short and doesn’t need updating when the source changes its API contract.
class: info.magnolia.openapi.client.OpenApiRestClientDefinition
schemaUrl: https://en.wikipedia.org/api/rest_v1/?spec Sadly, some content sources do not comply with the OpenAPI specification, and you have to define each call one by one, including the parameters to get the result. In the below example, we define a REST client with a REST call to the /posts URL.
baseUrl: https://jsonplaceholder.typicode.com
restCalls:
all:
method: get
entityClass: com.fasterxml.jackson.databind.JsonNode
path: /posts
Read the documentation to learn more about the YAML configuration and authentication.
Magnolia Multisource
With Multisource, Magnolia makes it fast and easy to connect to any external content or data source with just a few lines of configuration.
Tips and tricks
Test calls to the REST API
I recommend using tools to ensure that the REST API works as you expect. The first tool I recommend is cUrl, a CLI command to make REST calls. It is very fast and widely used by developers. HTTPie is similar but presents the results in a better way. Learning these tools increases your knowledge of the HTTP protocol and is worth the time.
The third tool, which is also widely used, is Postman. It is a graphical interface to make REST calls. It is easy to use and offers the option to save configurations allowing you to re-run tests when the API changes. Besides, you can share configurations with colleagues.
Debug REST calls using the Magnolia app
Magnolia Multisource comes with a tool to debug calls to a REST API. The app in the AdminCentral is called ‘REST Client’. It shows REST clients defined in your instance and allows you to initiate REST calls to check the results. You can change the call parameters if needed.
In the ‘Debug’ tab, you can select a REST client and monitor its live activity, meaning you have to keep the app open while making the calls. The tool shows details of the request as well as the response. Debug is also useful to check how calls are made to reproduce them with the cUrl command.
Login to our demo instance to see the REST Client interface in action.
Use the right response type
If you are not using the OpenAPI specification, you define the entityClass property for each REST call. For example, when working on the client, you want to convert the result to java.lang.String and have Javascript parse the JSON object. Or you might want to map the result to a POJO that you defined in your application.
When using the REST client with UI components, the entityClass is com.fasterxml.jackson.databind.JsonNode. When using the client directly, you can define another entityClass for example java lists, strings, or maps. The Jackson library will try to convert the response to the defined entityClass.
It can also be useful to have different REST calls with different response types for various purposes.
Conclusion
Most organizations store content in various places creating challenges for authors and front-end developers. To use dispersed content within Magnolia, Multisource makes integrations of third-party content sources a lot easier.
Even if you aren’t a Java developer, you can use Magnolia’s Light Development to set up REST clients for third-party APIs and use their content in your pages and apps through the AdminCentral UI. If you follow the above tips, you should configure an integration in no time.
