Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
HTML Wrap | ||||
---|---|---|---|---|
| ||||
Related topics: |
This page is intended for developers who want to start using Magnolia REST features.
In this page, we:
...
Excerpt |
---|
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
...
.
Table of Contents | ||||
---|---|---|---|---|
|
This section is a very brief summary of the most important things from the sections below.
To use Magnolia REST features:
magnolia-rest-integration
, magnolia-rest-services
, magnolia-rest-content-delivery
(version 2.0 or higher). See REST module - Installing if needed.superuser
on the author instance and anonymous
user on the public instance at your own risk.Provide YAML configuration to enable the usage of the delivery endpoint in a light module.
Expand | |||||||||
---|---|---|---|---|---|---|---|---|---|
| |||||||||
Read Delivery endpoint API - YAML configuration for further details. |
cURL:
Code Pro |
---|
curl -X GET 'http://localhost:8080/magnoliaPublic/.rest/delivery/website/v1/travel/about' |
and GET
a REST.
In this section, we assume you are using a Magnolia bundle version 5.6 or higher and you know how to:
magnolia.resources.dir
property in the magnolia.properties
file.Bestpractice |
---|
We recommend you have one common directory for the |
Tip |
---|
If you do not know how to do all of this, see Set up a Magnolia bundle with all REST modules - step by step instead. |
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.
...
If you do not want to use the Swagger UI tools, skip ahead to security settings.
Multiexcerpt include | ||||
---|---|---|---|---|
|
To enable Swagger you must add magnolia-rest-tools
to your webapp(s).
Add the following snippet to the pom file of your webapp:
Artifact maven dependencies snippet | ||||
---|---|---|---|---|
|
If you are running a preconfigured Magnolia Tomcat bundle:
Artifact resource link | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
$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.
...
MultiExcerptName | setting-swagger-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:
Code Block | ||
---|---|---|
| ||
<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
.
Tip |
---|
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.
Example | Website | REST 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: | ||
Run a fulltext search for the word "landscape" in all the tours published to our public demo site using the default delivery endpoint: | ||
Filter on the .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: |
Anchor | ||||
---|---|---|---|---|
|
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.
Expand | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
|
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
...
enableHeadingAttributes | false |
---|---|
enableSorting | false |
class | m5-configuration-tree |
enableHighlighting | false |
...
Mgnl f |
---|
...
Mgnl f |
---|
...
Mgnl f |
---|
...
Mgnl p |
---|
...
http://localhost:8080/magnoliaAuthor/.rest
After setting the base path, restart Magnolia.
Swagger UI tools is in Dev > REST Tools.
...
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.
...
title | Expand to see the step by step procedure |
---|
...
Choose a directory to work in.
...
. In our example, we use the directory ~/dev/mgnl-rest-test-base
...
:
Code Block |
---|
...
cd ~/dev/mgnl-rest-test-base |
...
Download a bundle with Magnolia CLI.
Execute the Magnolia CLI jumpstart
command to get Magnolia 5.6.0:
Code Block |
---|
...
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
Jumpstart also sets the property magnolia.resources.dir
in the file magnolia.properties
.
...
:
Code Block | ||
---|---|---|
| ||
mgnl-rest-test-base/
├── apache-tomcat
├── light-modules
└── magnolia.zip |
We will need the light-modules
folder later on. Do not start the Tomcat server yet.
...
Add magnolia-rest tools to your bundle.
...
Artifact resource link | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
...
Go to the ~dev/mgnl-rest-test-base
...
Start Magnolia.
...
directory
...
and execute the
...
Magnolia CLI start
command:
Code Block |
---|
...
mgnl start |
...
When starting for the first time, Magnolia
...
Log in to the author instance.
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 password superuser
.
...
Have a look around Magnolia. Access the public instance with the URL http://localhost:8080/magnoliaPublic
...
Set the Swagger base API path.
In order to properly use the Swagger UI tools - which are used for development only - you must change one property in the configuration.
On the Admin UI, open the Configuration app and find the node /modules/rest-tools/config
. (You can use the URL http://localhost:8080/magnoliaAuthor/.magnolia/admincentral#app:configuration:browser;/modules/rest-tools/config:treeview: to go there directly.)
...
/.
...
...
Restart Magnolia.
Go to the shell where you started Magnolia.
To stop the server, press cmd
+ C
(on Mac) or ctrl
+ C
(on Windows). Give the server some time to properly shut down.
Then start it again:
Code Block |
---|
cd ~dev/mgnl-rest-test-base
mgnl start |
Anchor | ||||
---|---|---|---|---|
|
...
Multiexcerpt include | ||||
---|---|---|---|---|
|
You must read and understand REST security before enabling and using the REST endpoints in a productive environment.
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 ...
/
on every JCR workspace, granted by the superuser
Web access for the HTTP methods
Mgnl get |
---|
Mgnl put |
---|
Mgnl post |
---|
Mgnl delete |
---|
/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.
anonymous
in the public instanceThe public instance is typically visited by users who do not authenticate. These visits are done as the anonymous
user, who also has some permissions.
...
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/*
As you can see, anonymous user only has read access and can only access the Delivery endpoint. That is sufficient for the moment.
In a productive environment we highly recommend you create custom REST roles granting specific access for specific use cases.
...
Magnolia provides the following REST endpoints out-of-the-box:
Multiexcerpt include | ||||
---|---|---|---|---|
|
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.
You can also create your own custom endpoints.
In this section, we suggest some tools you can use to test the REST API without needing to develop a REST consuming client application. Testing your REST requests is useful when you are developing client apps and similar things that interact with the REST endpoints.
...
A browser provides only limited control to tailor a request without further add-ons. Requests are sent as GET
and you cannot add more request headers out of the box.
...
If you want to test on REST resources via GET
, which requires authetication to get assigned roles not provided to the anonymous
user: log in to Magnolia first; open a new tab in the same window (using the same session); and then request the REST resource.
Upgrade the browser with add-ons to extend its possibilities to control the request.
Before enabling and using the REST endpoints in a production environment, y ou must read and understand REST security .
...
cURL
is a command line tool. It can be used on most well-known operating systems.
...
On the first attempt of a request, use the -i
option to display all response headers.
If the response body is fine and delivers JSON, pretty-print and colorize the response body with tools such as jq.
If you have not installed magnolia-rest-tools
, which provides the Swagger UI tools, skip this section or see how to enable the swagger tools above.
...
Seamlessly integrated into the Magnolia Admin UI. Comfortable to use form-based interface.
...
The endpoints require specific annotations to make them appear on the Swagger UI tools. Delivery endpoint is not annotated and does not appear on the Swagger tools. REST request is sent by the user who logged into Magnolia; it is difficult to test with different users.
Go to Dev > REST Tools.
Multiexcerpt | ||
---|---|---|
| ||
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 the |
Click on one of the links to open a submenu that shows all supported operations provided by the endpoint.
Click List operations or Expand operations to get the details for the operations.
Here is an example for the nodes
endpoint
Mgnl get |
---|
Enter values at least for the mandatory parameters and click Try it out!.
Swagger shows the response code, the response headers and the response body:
The delivery endpoint is a REST API provided by Magnolia out-of-the-box. Use it for obtaining JCR data as JSON.
In addition to defining security settings, you You must provide YAML-based configuration for the delivery endpoint so that it can serve JSON.
...
Code Pro | ||
---|---|---|
| ||
curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/delivery/website/v1/travel/about' \ -u superuser:superuser |
Anchor | ||||
---|---|---|---|---|
|
Magnolia provides the following REST endpoints out-of-the-box:
Multiexcerpt include | ||||
---|---|---|---|---|
|
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.