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: |
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 This page is intended for developers which want to start using the Magnolia REST features. We will show how to setup Magnolia in order to use all the REST functions provided by Magnolia. We quickly explain the available REST endpoints. And we give you an idea how you can test and use these endpoints.
Table of Contents | ||||
---|---|---|---|---|
|
This section is a brief summary of the most important things from the sections below. Here we will not go into details but mention the most important points.
We assume you are using Magnolia bundle with version 5.6 or higher and you know how you can:
magnolia.resources.dir
property in the magnolia.properties
file.Note |
---|
We recommend to have one common directory for the |
If you are unsure how to to set a common path for the magnolia.resources.dir
, please refer to the beginners tutorial Hello Magnolia, or use Magnolia CLI - jumpstart.
These three modules listed below are required to use all Magnolia REST features within a productive context.
magnolia-rest-integration
magnolia-rest-services
magnolia-rest-content-delivery
When using a preconfigured preconfigured Magnolia bundle - your webapp(s) already contain(s) these three modules. When using a custom webapp or bundle, make sure your custom setup contains the module listed above. See REST module - Installing if you need help to install the Magnolia REST modules.
While developing new features, it can be helpful to use the magnolia-rest-tools
which enable the swagger UI tools. Have a look at enabling swagger UI tools.
...
Multiexcerpt include | ||||
---|---|---|---|---|
|
If you do not want to usw the swagger tools- skip the next sections and proceed with reading about Getting started with Magnolia REST.
To enable swagger you must add magnolia-rest-tools
to your webapp(s).
With Maven
add the folowwing snippet to the pom file of your webapp:
Artifact maven dependencies snippet | ||||
---|---|---|---|---|
|
With a downloaded bundle
If you are running a preconfigured Magnolia Tomcat bundle:
Artifact resource link | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
|
$tomcat/webapps/magnoliaAuthor/WEB-INF/libs
$tomcat/webapps/magnoliaPublic/WEB-INF/libs
(if the direcory already exists).*) The zip file may contain .jar files which are already present in the WEB-INF/libs
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 |
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 out-of-the-box .rest/delivery/tours/v1/magnolia-travels/A-Taste-of-Malaysia | ||
Get all content from a sub-resource using the out-of-the-box | ||
Run a full text search for the word "landscape" in all the tours published to our public demo site using the out-of-the-box | ||
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 out-of-the-box | ||
Get all content in a specific language from a sub-resource using the out-of-the-box |
Anchor | ||||
---|---|---|---|---|
|
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
:
Code Block |
---|
cd ~/dev/mgnl-rest-test |
Execute the Magnolia CLI jumpstart
command to get Magnolia and choose the magnolia-community-demo-bundle
when prompted:
Code Block |
---|
mgnl jumpstart |
Jumpstart downloads and extracts the magnolia-community-demo-bundle
that comes with Tomcat server.
The following files and folders are created:
Code Block | ||
---|---|---|
| ||
mgnl-rest-test/
├── apache-tomcat
├── downloads
└── light-modules |
Go to the ~dev/mgnl-rest-test
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.
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/.
Anchor | ||||
---|---|---|---|---|
|
Multiexcerpt include | ||||
---|---|---|---|---|
|
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:/
on every JCR workspace, granted by the superuser
role.Web access for the HTTP methods
Mgnl get |
---|
Mgnl put |
---|
Mgnl post |
---|
Mgnl delete |
---|
/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 and using the REST endpoints in a production environment, you must read and understand REST security.
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 at least one endpoint configuration to use the delivery API.
delivery
endpointWe 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:
Code Block |
---|
define-delivery-endpoint/
└── restEndpoints/
└── delivery/
└── demo-content.yaml |
You can use this code to start with for the demo-content.yaml
file:
Code Pro | ||||||
---|---|---|---|---|---|---|
| ||||||
class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
workspace: website
depth: 2
nodeTypes:
- mgnl:page
- mgnl:area
- mgnl:component
childNodeTypes:
- mgnl:area
- mgnl:component
includeSystemProperties: false |
You can find a full explanation of the properties on Delivery endpoint API configuration.
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:
delivery/demo-content
.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:
Code Pro | ||
---|---|---|
| ||
curl -X GET ' .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/ magnoliaAuthormagnoliaPublic/.rest. /delivery/demo-content/travel/about' |
Code Pro | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
curl -X GET ' Advanced Tables - Table Plus | | |||||||
| ||||||||
Node name | Value |
|
|
|
|
...
...
/delivery/demo-content/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 using light modules. With the Commands endpoint you can trigger commands and Cache endpoint deals with cache.
..
...
To get started it is fine if you use the rest roles which come with the default setup of your preconfigured Magnolia bundle.
...
...
..
...