Getting started with REST

This page is intended for developers who want to start using Magnolia REST features.

In this page, we:

• Show how to set up Magnolia in order to use all the REST functions provided by Magnolia.
• Give an overview of the available REST endpoints.
• Propose a few tools you can use while exploring the REST endpoints.
• Show how to configure and use the delivery endpoint.

Setup

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

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

Required modules

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

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

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

When developing new features, it can be helpful to use the magnolia-rest-tools module which enables 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.

If you do not want to use the Swagger UI tools, 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 the following 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.
• 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 directory 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 .

After setting the base path, restart Magnolia.

Swagger UI tools is in Dev > REST Tools.

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

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

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

mgnl jumpstart

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

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

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

Security settings

We have warned you

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

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:

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

cURL

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

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.

Starting the swagger tools

Go to Dev > REST Tools.

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

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

Here is an example for GET of the nodes endpoint:

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:

Using the delivery endpoint

The Delivery endpoint is the latest 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.

Configuring the delivery enpoint

For the YAML based configuration of the delivery endpoint - let us create a light module.

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

To start with - the file delivery-base-definition.yaml can look like this:

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

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

• Line 3: website is the name of the so called "endpoint prefix" - in our case it is also the name of a JCR workspace. We will use the value of the endpoint prefix later on within the REST request URL.
• Everything below line 3 in the file above defines this endpoint prefix.
• You can define further endpoint prefixes.
• Make sure you have only one YAML based endpoint definition.

Reading website content with the delivery endpoint

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

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

• The name of  endpoint prefix => website
• The relative path of the node - relative to what is defined in the configuration as rootPath: => travel/about

URL => /.rest/delivery/website/v1/travel/about

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

• http://localhost:8080/magnoliaPublic/.rest/delivery/website/v1/travel/about
• http://localhost:8080/magnoliaAuthor/.rest/delivery/website/v1/travel/about

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

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

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

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