Getting started with REST

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.

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 don’t have Magnolia CLI, install it as described Getting started: Installing CLI. Then, install Magnolia as follows:

  1. Change to the directory where you want to install the Magnolia bundle. In our example, we use the directory ~/dev/mgnl-rest-test:

    cd ~/dev/mgnl-rest-test

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

    mgnl -- jumpstart

    Jumpstart downloads and extracts the travel-demo-community-webapp and a Tomcat server.

    The following folders and files are created:

    mgnl-rest-test/
├── apache-tomcat/
├── light-modules/
├── mgnl.config.js
├── mgnl.error.log
├── node_modules/
├── package-lock.json
└── package.json

  3. In the mgnl-rest-test directory, 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.

Before enabling and using the REST endpoints in a production environment, get familiar with the REST security topic.

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:

  • the superuser, the account you log in with to the author instance, has:

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

    • Web access for the HTTP GET and POST methods for the /.rest/* path, granted by the rest-admin role, and for the /* path, granted by the superuser role.

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

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

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 magnolia.resources.dir property, create the following structure:

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

Use this code to start with for the demo-content.yaml file:

demo-content.yaml
$type: jcrDeliveryEndpoint_v2
workspace: website
depth: 2
nodeTypes:
  - mgnl:page
  - mgnl:area
  - mgnl:component
childNodeTypes:
  - mgnl:area
  - mgnl:component

You can find a full explanation of the properties on Delivery endpoint API configuration.

Requesting website content

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

For example, try to retrieve the content of the /travel/about page on the website workspace.

Have a look at Delivery endpoint API: Read node to understand how to compose the URL.

For this particular case, you need to use a URL that contains:

  • The endpoint path: delivery/demo-content.

  • The relative path of the node: travel/about.

The URL should then contain /.rest/delivery/demo-content/travel/about.

Next, add the context (the name of the webapp), the domain and the protocol, and you get this URL: http://localhost:8080/magnoliaAuthor/.rest/delivery/demo-content/travel/about.

You are ready to test the endpoint, for example with cURL. Execute the following curl command:

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

Click to see the response.

{
  "@name": "about",
  "@path": "/travel/about",
  "@id": "808ebe4c-72b2-49f1-b9f7-e7db22bce02f",
  "@nodeType": "mgnl:page",
  "hideInNav": false,
  "title": "About",
  "main": {
    "@name": "main",
    "@path": "/travel/about/main",
    "@id": "f3b2681f-e747-4ff6-bcbb-2a9a9f01553e",
    "@nodeType": "mgnl:area",
    "00": {
      "@name": "00",
      "@path": "/travel/about/main/00",
      "@id": "01db6fc1-78af-4284-adf0-8c997309df6a",
      "@nodeType": "mgnl:component",
      "text": "<p>We are a full service, independent travel agency.</p>\n<p>We offer unique tours from every continent on the planet. Get inspired and book your tour with us for an experience you&rsquo;ll always remember.</p> ",
      "imagePosition": "below",
      "headlineLevel": "small",
      "headline": "About Magnolia Travels",
      "@nodes": []
    },
    "04": {
      "@name": "04",
      "@path": "/travel/about/main/04",
      "@id": "834ef0b0-1519-4834-b1f5-4166ae004ac0",
      "@nodeType": "mgnl:component",
      "layout": "8x4",
      "@nodes": []
    },
    "@nodes": [
      "00",
      "04"
    ]
  },
  "footer": {
    "@name": "footer",
    "@path": "/travel/about/footer",
    "@id": "21da1190-52e6-45d5-8e68-5a2878733d6c",
    "@nodeType": "mgnl:area",
    "footer1": {
      "@name": "footer1",
      "@path": "/travel/about/footer/footer1",
      "@id": "7b1bb2e5-4a96-46ba-9e37-213d49bd874f",
      "@nodeType": "mgnl:area",
      "@nodes": []
    },
    "footer2": {
      "@name": "footer2",
      "@path": "/travel/about/footer/footer2",
      "@id": "847f6b8c-a997-4c1a-ad7f-00c777351f32",
      "@nodeType": "mgnl:area",
      "@nodes": []
    },
    "footer3": {
      "@name": "footer3",
      "@path": "/travel/about/footer/footer3",
      "@id": "8d80386e-d6b7-489b-881a-b50a391fc08e",
      "@nodeType": "mgnl:area",
      "@nodes": []
    },
    "footer4": {
      "@name": "footer4",
      "@path": "/travel/about/footer/footer4",
      "@id": "83939ec7-c633-4bc0-a2f0-e874ac64b327",
      "@nodeType": "mgnl:area",
      "@nodes": []
    },
    "lastLinks": {
      "@name": "lastLinks",
      "@path": "/travel/about/footer/lastLinks",
      "@id": "5a9f3338-a98d-4797-b35e-0d9f10550a1e",
      "@nodeType": "mgnl:area",
      "@nodes": []
    },
    "@nodes": [
      "footer1",
      "footer2",
      "footer3",
      "footer4",
      "lastLinks"
    ]
  },
  "@nodes": [
    "main",
    "footer"
  ]
}

Additional examples

The examples below show how to get content from the out-of-the-box tours_v1 delivery endpoint in our public demo.

Mozilla Firefox includes a JSON viewer you can use to view the responses in a more human-friendly format.
Related topics
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules