Versions Compared

Old Version 127

changes.mady.by.user Julie Legendre

Saved on

compared with

New Version 128

changes.mady.by.user Julie Legendre

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: step by step instructions in table

...

Table of Contents
maxLevel3
minLevel2

Tip
iconfalse
Short version - tl;dr

Key points

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

To use Magnolia REST features:

  • Set up Magnolia with version 5.6 or higher, ; you may want to use a preconfigured Magnolia bundle.
  • Make sure the your bundle contains at least the Magnolia REST modules magnolia-rest-integration, magnolia-rest-services, magnolia-rest-content-delivery (version 2.0 or higher). See REST module - Installing if you need helpneeded.)
  • Design a security concept strategy with custom users to access the REST endpoint. Right now and To start immediately or for testing reasons - purposes, you can use superuser on the author instance and anonymous user on the public context - instance at your own risk.

  • Provide

    a

    YAML configuration to enable the usage of the

    Delivery

    delivery endpoint in a

    Light

    light module.

    Expand
    titleClick here to expand to get a version to startstarting point for configuration


    Code Pro
    languageyaml
    titledelivery-base-definition.yaml
    linenumberstrue
    class: info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpointDefinition
params:
  website:
    depth: 2
    nodeTypes:
      - mgnl:page
      - mgnl:area
      - mgnl:component
    childNodeTypes:
      - mgnl:area
      - mgnl:component
    rootPath: /
    includeSystemProperties: false

    Read Delivery endpoint API - YAML configuration for further details.


  • cURL:

    Code Pro
    curl -X GET 'http://localhost:8080/magnoliaPublic/.rest/delivery/website/v1/travel/about'

    and

    Mgnl get

    GET a REST.

Setup

We In this section, we assume you are using a Magnolia bundle with version 5.6 or higher and you know how you canto:

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

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


Tip

If you

...

do not know how to do all of this, see Set up a Magnolia bundle with all REST modules - step by step instead.

Required modules

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

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

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

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

Anchor
enabling-swagger-tools
enabling-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 use the swagger Swagger UI tools- skip the next sections and proceed with reading about security, skip ahead to security settings.

Installing the magnolia-rest-tools module

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

With Maven

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

Artifact maven dependencies snippet
groupIdinfo.magnolia.rest
artifactIdmagnolia-rest-tools

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 the REST tools bundle 
    Artifact resource link
    groupIdinfo.magnolia.rest
    artifactIdmagnolia-rest-tools
    label$artifactId.zip
    renderTypedownload_link
    versionSNAPSHOT
    resourceTypeZIP
    .
  • Unzip the download and copy* all the files to to: 
    • $tomcat/webapps/magnoliaAuthor/WEB-INF/lib
    • $tomcat/webapps/magnoliaPublic/WEB-INF/lib (if the direcory directory already exists).

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

...

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 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 UI tools is in Dev > REST Tools.

Anchor
setup-step-by-step
setup-step-by-step
Setup Set up a Magnolia bundle with all REST modules - step by step

This section provides a step by step series of instructions to setup set up a Magnolia bundle which that contains all REST modules inclusing including the magnolia-rest-tools module to use the swagger Swagger UI tools. The procedure is using the uses Magnolia CLI. If you are an experienced Magnolia user, you can skipt skip this and setup set up Magnolia by in your prefered preferred style.

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


StepInstructions
1

Choose

#1 Get the shell and choose

a directory to work

with

in.

Open a shell and change to the 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


2

Download a bundle with Magnolia 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

Once jumpstart is

done

executed, your directory looks like this:

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

We will need the light-modules

 folder

folder later on.

Please do

(warning) Do not start the

tomcat so far

Tomcat server yet.

#3 Adding the
3

Add magnolia-rest tools to

the

your bundle.

 Download the Rest

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

and copy all the files

of

from 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
#4

Start Magnolia.

You are ready to start

Magnolia - actually

the Tomcat server

-

for the first time. Go to

our

the "root" directory (/dev/mgnl-rest-test-base) and execute the CLI command start:

Code Block
cd ~dev/mgnl-rest-test-base
mgnl start
Give Magnolia some time. On the first

(info) During the initial start up, Magnolia installs a lot of configuration data and demo content bootsrapped with its modules - this may take some time.

#5 Login on
5

Log in to the author

context

instance.

Open

In your

favorite

preferred browser, open the URL http://localhost:8080/magnoliaAuthor/ and

login

log in as user superuser with the password superuser.

Now you are nearly done.

Play around a little bit with

Have a look around Magnolia.

Also go to

Access the public

context

instance with the URL http://localhost:8080/magnoliaPublic/ .

6
#6

Set the

swagger

Swagger base

api

API path.

In order to properly use the

swagger

Swagger UI tools - which are used for development only -

we

you must

adapt

change one property in the configuration.

On the UAdmin

-

, open the Configuration app and

open

find 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

config folder and change the value of the apiBasepath property to: 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

7

Restart Magnolia.

Go to the shell where you

have

started Magnolia.

To stop the server

-

, press cmd + C (on

a mac

Mac) or ctrl + C (on Windows). Give the server some time to properly

shutdown

shut down.

Now

Then start it again:

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



Anchor
security
security
Security settings

...

Downloadhttps://curl.haxx.se/download.html
PositiveVery flexible to tailor the request (method, request headers, user credentials, etc.). Response can be further processed.
NegativeNot everybody likes command line tools. The response is not easy 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.

Image Modified

Swagger UI tools

If you have not installed magnolia-rest-tools with the swagger UI tools, skip this section, or see above about how to enable the swagger tools.

Positive

Seamless integrated into the Magnolia UAdmin. Comfortable to use form based interface.

Negative

The endpoints require specific annotations to make them appear on the swagger UI tools. Delivery endpoint is not annotated and will not appear on the swagger tools. REST request is sent by the user which logged into Magnolia; cumbersome to test with different users.

Starting the swagger tools

Go to Dev > REST Tools.

Multiexcerpt
MultiExcerptNameswagger-start

When you open the the Magnolia REST Tools app, you should see something similar to this screen: 

The Swagger UI lists the bundled endpoints which already have Swagger annotations. These are the endpoints from magnolia-rest-services module (propertiesv1, commandsv2, nodesv1) and one from the cache-browser-app (cachev1).

...