Page History

...

This  This beginner's tutorial is intended for developers who want to start using Magnolia REST features.

...

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 5.6.0 bundleMagnolia bundle with the required modules for Magnolia REST features.

...

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

...

.

...

...

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

...

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:

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

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

   Code Block
   mgnl jumpstart -m 5.6

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

   The following files and folders are created:

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

3. Go to the ~dev/mgnl-rest-test-base directory  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.

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

...

• • Read/Write access for the path / on every JCR workspace, granted by the  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.

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

  • Read access on the path / for the JCR workspaces website, dam, googleSitemaps, category, and tours.

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

Before  enabling Before enabling and using the REST endpoints in a  production  environment, y ou a production environment, you must read and understand 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. 

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 YAML-based configuration for the delivery endpoint so that it can serve JSON.at least one endpoint configuration to use the delivery API. 

Configuring the delivery endpoint

We will create a light module to provide the YAML-based configuration required for the delivery 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 light-modules folder, which is configured with the property magnolia.resources.dir, create the following structure:

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

You can use this code to start with for the delivery-base-definitionthe demo-content.yaml 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

You can find a full explanation of the properties 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

...

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

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

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.

...

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

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

...

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

...