Getting started with Magnolia REST

This page is intended for developers which want to start using the Magnolia REST features. We will show how to setup Magnolia in order to use all the REST functions provided by Magnolia. We quickly explain the available REST endpoints. And we give you an idea how you can test and use these endpoints.

Short version - all in 10'

This section is a brief summary of the most important things from the sections below. Here we will not go into details but mention the most important points.

Get a preconfigured Magnolia bundle with version 5.6 or higher and start the bundle.

Setup

We assume you are using Magnolia bundle with version 5.6 or higher and you know how you can:

Install Magnolia
Set the magnolia.resources.dir property in the magnolia.properties file.
Start and stop Magnolia.

We recommend to have one common directory for the magnolia.resources.dir on both webapps magnoliaAuthor and magnoliaPublic. We will use that later on for a shared configuration.

If you are completely new to Magnolia, follow Setup a Magnolia bundle with all REST modules - step by step.

Required modules

These three modules listed below are required to use all Magnolia REST features within a productive context.

magnolia-rest-integration
magnolia-rest-services
magnolia-rest-content-delivery

When using a preconfigured preconfigured Magnolia bundle - your webapp(s) already contain(s) these three modules. When using a custom webapp or bundle, make sure your custom setup contains the module listed above. See REST module - Installing if you need help to install the Magnolia REST modules.

While developing new features, it can be helpful to use the magnolia-rest-tools which enable the swagger UI tools. Have a look at enabling swagger UI tools.

Enabling swagger UI tools - magnolia-rest-tools

The Swagger framework is supported by a set of core tools for designing, building, and documenting RESTful APIs.
Source: https://swagger.io/tools/

Magnolia provides integration with Swagger tools directly in the Admin UI.

Swagger tools are for development and testing purposes only.

If you do not want to usw the swagger tools- skip the next sections and proceed with reading about Getting started with Magnolia REST.

Installing the magnolia-rest-tools module

To enable swagger you must add magnolia-rest-tools to your webapp(s).

With Maven

add the folowwing snippet to the pom file of your webapp:

Error rendering macro 'artifact-maven-dependencies-snippet-macro'

com.sun.jersey.api.client.ClientHandlerException: java.net.NoRouteToHostException: No route to host (Host unreachable)

With a downloaded bundle

If you are running a preconfigured Magnolia Tomcat bundle:

Stop the Tomcat server (if it was alrewady started).
Download the Rest tools bundle
Error rendering macro 'artifact-resource-macro'
com.sun.jersey.api.client.ClientHandlerException: java.net.NoRouteToHostException: No route to host (Host unreachable)
.
Unzip the download and copy* all the files to
- $tomcat/webapps/magnoliaAuthor/WEB-INF/libs
- $tomcat/webapps/magnoliaPublic/WEB-INF/libs (if the direcory already exists).

*) The zip file may contain .jar files which are already present in the WEB-INF/libs folder of your webapps.

Set the Swagger API base path

The Swagger API explorer tool searches for the API at a path set in /modules/rest-tools/config/apiBasepath. The default value is http://localhost:8080/.rest. The value for this property must match the following pattern:

<protocol>://<hostname>:<port>/<context>/.rest

When using one of Magnolia's preconfigured bundles running on localhost, set the property to http://localhost:8080/magnoliaAuthor/.rest.

Set the path to where REST services reside on your system. If you run the standard Magnolia bundle and work on the author instance, set the path to http://localhost:8080/magnoliaAuthor/.rest.

Node name	Value
modules
rest-tools
config
apiBasepath	http://localhost:8080/magnoliaAuthor/.rest

After setting the base path, restart Magnolia.

Swagger is in Dev > REST Tools.

Setup a Magnolia bundle with all REST modules - step by step

In this section follows a step by step series of instructions to setup a Magnolia bundle which contains all REST modules inclusing magnolia-rest-tools to use the swagger UI tools. The procedure is usng the Magnolia CLI.

#1 Get the shell and choose a directory to work with

Open a shell and change to directory of your choice. In our example, we use the directory ~/dev/mgnl-rest-test-base.

cd ~/dev/mgnl-rest-test-base

#2 Downloading a bundle with CLI jumpstart

mgnl jumpstart

Jumpstart downloads and extracts the latest version of magnolia-community-demo-bundle which comes with Tomcat server. Use the -e option to get the magnolia-enterprise-pro-demo-bundle - which will prompt for enterprise credentials. See jumpstart for further options.

Jumpstart also sets the property magnolia.resources.dir in the file magnolia.properties - which is fine.

When the execution of jumpstart is done, your directory looks like this:

mgnl-rest-test-base/
├── apache-tomcat
├── light-modules
└── magnolia.zip

We will need the light-modules folder later on. Please do not start the tomcat so far.

#3 Adding the magnolia-rest tools to the bundle

Download

Security settings

To get started it is fine if you use the rest roles which come with the default setup of your preconfigured Magnolia bundle.

...

Testing the setup

..

The endpoints - an overview

...

My first REST request

..

Page tree