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.
Getting content with REST - examples
Look at the following examples of how to get content from our public demo using our out-of-the-box REST API.
Mozilla Firefox includes a JSON viewer. We suggest you use Firefox to view the links below in a more readable format. |
Example | Website | REST result |
---|---|---|
Get one specific item using the out-of-the-box |
|
|
Get all content from a sub-resource using the out-of-the-box
|
|
|
Run a full text search for the word |
|
|
Filter on the |
|
|
Get tour content limited to five results and and offset to begin at
number ten using the out-of-the-box |
|
|
Get all content in a specific language from a sub-resource using the
out-of-the-box |
|
|
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:
-
Change to the directory to where you want to install the Magnolia bundle. In our example, we use the directory
~/dev/mgnl-rest-test
:cd ~/dev/mgnl-rest-test
-
Execute the Magnolia CLI
jumpstart
command to get Magnolia and choose themagnolia-community-demo-webapp
when prompted:mgnl jumpstart
Jumpstart downloads and extracts the
magnolia-community-demo-webapp
and a Tomcat server.The following files and folders are created:
mgnl-rest-test/ ├── apache-tomcat ├── downloads └── light-modules
-
Go to the
~dev/mgnl-rest-test
directory and execute the Magnolia CLIstart
command:mgnl start
When starting for the first time, Magnolia runs a web update and automatically installs all its modules.
-
In your preferred browser, open the URL http://localhost:8080/magnoliaAuthor/ and log in as user
superuser
with the passwordsuperuser
. -
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 thesuperuser
role. -
Web access for the HTTP methods GET, PUT, POST and DELETE for the path
/magnoliaAuthor/.rest*
granted by the rolerest-admin
. -
anonymous
(unauthenticated user) in the public instance has:-
Read access on the path
/
for the JCR workspaceswebsite
,dam
,googleSitemaps
,category
, andtours
. -
Web access for the HTTP method
GET
for the path/magnoliaAuthor/.rest/delivery/*
-
Before enabling and using the REST endpoints in a production environment, you 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.
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 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/ └── demo-content.yaml
You can 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.
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 endpoint path: in our case evaluated by the system as
delivery/demo-content
. -
The relative path of the node:
travel/about
.
URL ⇒ /.rest/delivery/demo-content/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/demo-content/travel/about'
curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/delivery/demo-content/travel/about' \
-u superuser:superuser
REST endpoints overview
Magnolia provides the following REST endpoints out-of-the-box:
See Delivery API for more information. |
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.