Page tree
Skip to end of metadata
Go to start of metadata

REST endpoints enable other software to get real, raw content directly from Magnolia. This is how mobile apps, front-end JavaScript apps, or systems, like e-commerce or banking systems, can connect with Magnolia. With our out-of the-box delivery endpoint, this is easy and fast to set up, more powerful and more performant than ever. This beginner's tutorial is intended for developers who want to start using Magnolia REST features.

Getting content with REST - examples

Mozilla Firefox includes a JSON viewer. We suggest you use Firefox to view the links below in a more readable format.

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

ExampleWebsiteREST result

Get one specific item using the default delivery endpoint. In this example we get a specific tour published to our public demo site by providing the path:

.rest/delivery/tours/v1/magnolia-travels/A-Taste-of-Malaysia

Get all content from a sub-resource using the default delivery endpoint. In this example we get all the tours published to our public demo site:

.rest/delivery/tours/v1

Run a fulltext search for the word "landscape" in all the tours published to our public demo site using the default delivery endpoint:

.rest/delivery/tours/v1/?q=landscape

Filter on the isFeatured property and on tags health and sale applied to tours using the default delivery endpoint:

.rest/delivery/tours/v1/?isFeatured=true&mgnl:tags=health&mgnl:tags=sale

Get tour content limited to five results and and offset to begin at number ten using the default delivery endpoint:

.rest/delivery/tours/v1/?limit=5&offset=10

Setting up Magnolia for REST

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

 Hey, why 5.6.0?

The latest version of Magnolia is 5.6.1 so you're right to wonder.

Currently in Magnolia, we only support a single delivery endpoint configuration. In Magnolia 5.6.1, a preconfigured endpoint is delivered by default making it a little difficult to create your own endpoint later on in this tutorial. Magnolia 5.6.0 does not deliver a preconfigured endpoint.

Soon this point will be moot as we plan to support multiple endpoints. Keep an eye on MGNLREST-152 - Getting issue details... STATUS to see how development is coming along!

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. In our example, we use the directory ~/dev/mgnl-rest-test-base:

    cd ~/dev/mgnl-rest-test-base
  2. Execute the Magnolia CLI  jumpstart  command to get Magnolia 5.6.0:

    mgnl jumpstart -m 5.6

    Jumpstart downloads and extracts the magnolia-community-demo-bundle 5.6.0 that comes with Tomcat server. 

    The following files and folders are created:

    mgnl-rest-test-base/
    ├── apache-tomcat
    ├── light-modules
    └── magnolia.zip
  3. Go to the ~dev/mgnl-rest-test-base directory and execute the Magnolia CLI  start  command:

    mgnl start

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

  4. In your preferred browser, open the URL http://localhost:8080/magnoliaAuthor/ and log in as user superuser with the password superuser.

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

Security settings

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

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, granted by the  superuser role.
    • Web access for the HTTP methods GETPUTPOST and DELETE for the path /magnoliaAuthor/.rest*  granted by the role rest-admin.

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

    • Read access on the path / for the JCR workspaces websitedamgoogleSitemapscategory, and tours.

    • Web access for the HTTP method GET  for the path /magnoliaAuthor/.rest/delivery/*

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

Using the delivery endpoint

The delivery endpoint is a REST API provided by Magnolia out-of-the-box. Use it for obtaining JCR data as JSON. 

You must provide YAML-based configuration for the delivery endpoint so that it can serve JSON.

Configuring the delivery endpoint

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

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

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

You can use this code to start with for the delivery-base-definition.yaml file:

delivery-base-definition.yaml
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
You can find a full explanation on Delivery endpoint API - YAML configuration.

For the time being, note the following points:

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

Reading website content with the delivery endpoint

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

We will 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 protocol, and you get these URLs:

You can request the first URL, which goes to the public instance, with the browser as the anonymous user (without authentication). For the second URL, 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

REST endpoints overview

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

EndpointHTTP methodsSwagger UI enabled
delivery

GET

Read node.
Query nodes.

----
nodes

GET

PUT

POST

DELETE

Read nodeCreate nodeUpdate nodeDelete node
properties

GET

PUT

Create property

POST

Update property

DELETE

Read propertyDelete property
commands

-

-

POST

Execute command

-

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 via light module. With the Commands endpoint you can trigger commands and Cache endpoint deals with cache. 

Further reading