Versions Compared

Old Version 48

changes.mady.by.user Christoph Meier

Saved on

compared with

New Version 49

changes.mady.by.user Christoph Meier

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Table of Contents
maxLevel3
minLevel2

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. 

Setup

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

...

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. 

...

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.

Anchor
using-swagger-tools
using-swagger-tools
Enabling swagger UI tools - magnolia-rest-tools

Multiexcerpt include
MultiExcerptNamegeneral_info
PageWithExcerpt_enabling and using swagger

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

Installing the magnolia-rest-tools module

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

...

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

Multiexcerpt
MultiExcerptNamesetting-swagger-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:

Code Block
languageerl
<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.

Advanced Tables - Table Plus
enableHeadingAttributesfalse
enableSortingfalse
classm5-configuration-tree
enableHighlightingfalse


Node nameValue

Mgnl f
modules


Mgnl f
rest-tools


Mgnl f
config


Mgnl p
apiBasepath

http://localhost:8080/magnoliaAuthor/.rest


After setting the base path, restart Magnolia.

Swagger is in Dev > REST Tools.

Anchor
setup-step-by-step
setup-step-by-step
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.

Expand
titleClick here to expand to see the step by step procedure

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

Code Block
languagebash
cd ~/dev/mgnl-rest-test-base

#2 Downloading a bundle with CLI jumpstart

Code Block
languagebash
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:

Code Block
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 

Artifact resource link
groupIdinfo.magnolia.rest
artifactIdmagnolia-rest-tools
label$artifactId.zip
renderTypedownload_link
versionSNAPSHOT
resourceTypeZIP
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:

Code Block
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.

No start it again:

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


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

...

Anchor
test-setup
test-setup
Testing the setup

..

The endpoints - an overview

...

My first REST request

..

Getting familiar with tools