Page History

 This beginner's tutorial is intended for developers who 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 give an overview of the available REST endpoints. We propose a few tools while you are exploring the REST endpoints. Finally we show ho to configure an use the delivery endpoint.

Getting content with REST - examples

Short version - tl;dr

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. 

Provide a YAML configuration to enable usage of the Delivery endpoint in a Light module.

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 -X GET 'http://localhost:8080/magnoliaPublic/.rest/delivery/website/v1/travel/about'

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.

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.

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.

...

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:

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 

  Artifact resource link
  groupId info.magnolia.rest artifactId magnolia-rest-tools label $artifactId.zip renderType download_link version SNAPSHOT resourceType ZIP

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

...

Look at the following examples of how to get content from our public demo using our out-of-the-box REST API.

Anchor
setup setup

Setting up Magnolia for REST

In this section you use Magnolia CLI to install and start a preconfigured Magnolia bundle with the required modules for Magnolia REST features.

If you do not have Magnolia CLI, install it as described here.

Then install Magnolia as follows:

1. Change to the directory to where you want to install the Magnolia bundle

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 .

...

...

...

...

...

...

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

After setting the base path, restart Magnolia.

Swagger is in Dev > REST Tools.

...

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

...

1. . In our example, we use the directory ~/dev/mgnl-rest-test

...

1. :

   Code Block

...

...

1. cd ~/dev/mgnl-rest-test

...

#2 Downloading a bundle with CLI jumpstart

2. Execute the Magnolia CLI jumpstart command to get Magnolia and choose the  magnolia-community-demo-bundle when prompted:

   Code Block

...

1. mgnl jumpstart

   Jumpstart downloads and extracts

...

1. the magnolia-community-demo-bundle

...

1.  that comes with Tomcat server.

...

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:

...

1.  

   The following files and folders are created:

   Code Block
   language text
   mgnl-rest-test

...

1. / ├── apache-tomcat ├──

...

1. downloads └──

...

1. light-modules

...

#3 Adding the magnolia-rest tools to the bundle

 Download the Rest tools bundle 

#4 Start Magnolia

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

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

Give Magnolia some time. On the first start up Magnolia installs a lot of configuration data and demo content bootsrapped with its modules.

#5 Login on the author context

...

2. Go to the ~dev/mgnl-rest-test directory and execute the Magnolia CLI start command:

   Code Block
   mgnl start

   When starting for the first time, Magnolia runs a web update and automatically installs all its modules.

3. In your preferred browser, open the URL http://localhost:8080/magnoliaAuthor/ and

...

1. log in as user superuser with the password superuser.

...

2. Have a look around Magnolia. Access the public instance with the URL http://localhost:8080/magnoliaPublic/

...

#6 Set the swagger base api path

...

1. .

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

Anchor
security security

Security settings

We have warned you

...

Multiexcerpt include
MultiExcerptName general-security-advice PageWithExcerpt REST security

.

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

In the context of this tutorial and to get started quickly,

...

we use users with roles provided by the default setup of

...

the Magnolia bundle

...

:

...

• superuser

...

•  in the author

...

• instance has:

...

• • Read/Write access for the path / on every JCR
workspace -
• • workspace, granted by the
role 
• •   superuser role.

  • Web access for the HTTP methods 

    Mgnl get

    , 

    Mgnl put

    , 

    Mgnl post

     and 

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

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.

...

• anonymous (unauthenticated user) in the public instance has:

  • Read access on the path /

  for

  •  for the JCR workspaces website, dam, googleSitemaps, category,

   

  • and tours.

  • Web access for the HTTP method 

  Mgnl get

   on the path  path 

  • GET  for the 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:

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 your 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 some tools to test the REST API - without the need to develop a REST consuming client application. Testing your REST requests is handy when you are developing client apps and similar things which will interact with the REST endpoints.

Browser

...

...

 Image Removed

cURL

cURL is a command line tool. It can be used on most of the well known operating systems.

...

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.

Before enabling and using the REST endpoints in a production environment, you must read and understand REST security.

Image Removed

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.

...

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

...

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.

Now click on one of the links - it will open a submenu which shows all supported operations provided by the endpoint.

Click List operations or Expand operations to get the detail forms for the operations.

Here is an example for 

Image Removed

Enter values at least for the mandatory parameters and click the button Try it out!.

Swagger will show the response code, the response headers and the response body:

Image Removed

Using the delivery endpoint

The Delivery delivery endpoint is the latest a REST API provided by Magnolia out-of-the-box. Use it for obtaining JCR data as JSON. Besides security settings - you must

provide YAML based configuration for the delivery endpoint - otherwise the endpoint can not serve JSON.With version 2 of the delivery endpoint API, you can define multiple endpoint configurations, deliver localized content and resolve references to nodes of other workspaces including assets and asset renditions. You must provide at least one endpoint configuration to use the delivery API. 

Configuring the delivery

...

endpoint

We will create a light module to provide For the YAML-based configuration of required for the delivery endpoint - let us create a light module.endpoint. 

Note that the folder structure and endpoint definition configuration file names you create now may later be used as the value of the endpointPath property. The endpoint path is used as part of the URL so we recommend you think ahead when naming your files.

In your Within the light-modules folder - , which is configured with the property magnolia.resources.dir, see above - create the following structure:

define-delivery-endpoint/
└── restEndpoints/
    └── delivery-base-definition/
        └── demo-content.yaml

To You can use this code to start with - for the file delivery-base-definitiondemo-content.yaml can look like this file:

class: info.magnolia.rest.delivery.jcr.v1v2.JcrDeliveryEndpointDefinition
paramsworkspace:
  website:
    depth: 2
    nodeTypes:
      - mgnl:page
      - mgnl:area
      - mgnl:component
    childNodeTypes:
      - mgnl:area
      - mgnl:component
    rootPath: /
    includeSystemProperties: false

To get all the details - please refer to You can find a full explanation of the properties on Delivery endpoint API - YAML configuration.

For the time being, you should know the following things:

...

.

...

Reading website content with the delivery endpoint

With the given configuration provided above - , you are ready to send REST requests to your Magnolia instance.

Let us We will fetch the content of the page /travel/about on the website workspace. Have a look at Delivery endpoint API - readNode - to  to understand how to compose the URL. We need:

• The name of  endpoint prefix => websiteendpoint path: in our case evaluated by the system as  delivery/demo-content .
• The relative path of the node - relative to what is defined in the configuration as rootPath: => : travel/about.

URL => /.rest/delivery/website/v1demo-content/travel/about

Now add the "context" (the name of the webapp), the domain and the protocoll - protocol, and you get this these URLs:

• http://localhost:8080/magnoliaPublic/.rest/delivery/websitedemo-content/v1/travel/about
• http://localhost:8080/magnoliaAuthor/.rest/delivery/websitedemo-content/v1/travel/about

The You can request the first URL, which goes to the public contextinstance, you can request with the browser as the anonymous user (without authentication). For the second request URL, you must authenticate.

To test these URLs with cURL, use the following commands:

curl -X GET 'http://localhost:8080/magnoliaPublic/.rest/delivery/website/v1demo-content/travel/about'

curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/delivery/website/v1demo-content/travel/about' \
-u superuser:superuser

Anchor
anc-restendpointsoverview anc-restendpointsoverview

REST endpoints overview

Magnolia provides the following REST endpoints out-of-the-box:

If you want to use REST to create, update and delete content, we recommend you use the Nodes endpoint which supports all required operations. If you mainly want to read data, consider using the Delivery endpoint. It provides convenient, formatted JSON and can be customized and configured with YAML using light modules. With the Commands endpoint you can trigger commands and Cache endpoint deals with cache. 

Further reading

• Tools to test REST requests

• REST API

• How to add an asset with REST

• How to create a custom Java-based REST endpoint.