Getting started with 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.

Set up Magnolia with version 5.6 or higher, you may want to use a preconfigured Magnolia bundle.
Make sure the bundle contains at least the Magnolia REST modules magnolia-rest-integration, magnolia-rest-services, magnolia-rest-content-delivery. Optionally also add magnolia-rest-tools (in this case make sure that you have properly configured the swagger api base path).
...

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.

Best practice

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

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/lib
- $tomcat/webapps/magnoliaPublic/WEB-INF/lib (if the direcory already exists).

*) The zip file may contain .jar files which are already present in the WEB-INF/lib 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

This section provides 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 using the Magnolia CLI. If you are an experienced Magnolia user, you can skipt this and setup Magnolia by your prefered style.

#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 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)

into a temporary folder. Unzip it. Copy all the files of the unzipped folder into ~/dev/mgnl-rest-test-base/apache-tomcat/webapps/magnoliaAuthor/WEB-INF/lib. Some of the files may already be there, that's fine.

#4 Start Magnolia

You are ready to start Magnolia - actually the Tomcat server - for the first time. Go to our "root" directory ans start with the CLI command start:

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

Give Magnolia some time. On the first start up Magnolia installs some configurations for a bunch of modules, etc. pp.

#5 Login on the author context

Open your favorite browser, open the URL http://localhost:8080/magnoliaAuthor/ and login as user superuser with the password superuser. Now you are nearly done. Play around a little bit with Magnolia. Also go to the public context with the URL http://localhost:8080/magnoliaPublic/.

#6 Set the swagger base api path

In order to properly use the swagger UI tools - which are used for development only - we must adapt one property in the configuration.

On the UAdmin - open the Configuration app and open the node /modules/rest-tools/config. (You can use the URL http://localhost:8080/magnoliaAuthor/.magnolia/admincentral#app:configuration:browser;/modules/rest-tools/config:treeview: to go there directly.)

Open the folder config and edit the property apiBasepath. Give it the value http://localhost:8080/magnoliaAuthor/.rest.

This property is one of the rare one which requires a server restart to make the change effective.

#7 Restart Magnolia

Go to the shell where you have started Magnolia.

To stop the server - press cmd + C (on a mac) or ctrl + C (on Windows). Give the server some time to properly shutdown.

Now start it again:

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

Security settings

We have warned you

REST endpoints are a powerful tool but can also make your site very vulnerable. Make sure you understand how to implement a strong security strategy to safeguard your system..

Please read and understand REST security before enabling and using the REST endpoints on a productive environment.

In the context of this tutorial to get started, you will use users with roles provided by the default setup of the the Magnolia bundle.

Using `superuser` on the author context - for testing reasons only!

On the author context use the superuser is granted:

Read/Write access for the path / on every JCR workspace - granted by the role superuser.
Web access for the HTTP methods GET, PUT, POST and DELETE for the path /magnoliaAuthor/.rest* - granted by the role rest-admin.

Note that superuser is given a lot of power. Use it carefully in the context of this tutorial. But never use superuser on a productive environment for REST.

Using `anonymous` user on the public context

The public context typically is visited by users which do not authenticate. Nevertheless, such visits are done as anonymous user - which also has some permissions.

On the public context anonymous user is granted:

Read access on the path / for the JCR workspaces website, dam, googleSitemaps, category, tours
Web access for the HTTP method GET on the path path /magnoliaAuthor/.rest/delivery/*

As you can see, anonymous user only has read access and can only access the Delivery endpoint. That is sufficient for the moment.

On a productive environment - we highly recommend to create custom REST roles granting specific access for specific use cases.

The endpoints - an overview

Magnolia provides out of the box the following REST endpoints:

Endpoint	HTTP methods				Swagger UI enabled
`delivery`	GET Read node. Query nodes.	-	-	-	-
`nodes`	GET	PUT	POST	DELETE	✓
`nodes`	Read node	Create node	Update node	Delete node	✓
`properties`	GET	PUT Create property	POST Update property	DELETE	✓
`properties`	Read property	PUT Create property	POST Update property	Delete property	✓
`commands`	-	-	POST Execute command	-	✓

If you want to use REST to create, update and delete content - we recommend using the Nodes endpoint which supports all required operations. If you mainly want to read data - consider using the Delivery endpoint. It provides a very handy formatted JSON and can be customized and configured with YAML via light module. With the Commands endpoint you can trigger commands. And <Cache endpoint> deals with cache. And you always can create ypur own custom endpoints - for inspiration see How to create a custom Java based REST endpoint.

Tools to test REST requests

On this section we propose som tools to test the REST API with some little tools - without the need to develop a REST consuming client application upfront.

Browser

Positive	For instance Firefox displays JSON and XML in a very well readable format.
Negative	A browser provides only limited control to tailor a request without further add-ons. Requests are sent as GET and you cannot add more request headers out of the box.
Tips	If you want to test on REST resources via GET, which requires authetication (to get assigned roles not provided to `anonymous` user - login at Magnolia first, open a new tab on the same window (using the same session) and then requesting the REST resource. Upgrade the browser with add-ons to extend its possibilities to controll the request.

cURL

cURL is a command line tool. It can be used on most of the well known operating systems. In this tutorial we will often test REST request via cURL.

Download	https://curl.haxx.se/download.html
Positive	Very flexible to tailor the request (method, request headers, etc.). Response can be further processed.
Negative	Not everybody likes command line tools. The response is not reasy to read without further tooling. No out of the box automatic URL encoding.
Tips	On the first atempt of a request use the `-i` option to display all response headers. If the response body is fine and delivers JSON, pretty print and colorize the response body with tools such as jq.

Swagger UI tools

.

Page tree