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 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.
magnolia-rest-integration
, magnolia-rest-services
, magnolia-rest-content-delivery
. Optionally also add magnolia-rest-tools
(in this case make sure that you have properly configured the swagger api base path).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.Bestpractice |
---|
We recommend to have one common directory for the |
If you are completely new to Magnolia, follow Setup a Magnolia bundle with all REST modules - step by step.
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.
Anchor | ||||
---|---|---|---|---|
|
Multiexcerpt include | ||||
---|---|---|---|---|
|
If you do not want to usw the swagger tools- skip the next sections and proceed with reading about security.
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/lib
$tomcat/webapps/magnoliaPublic/WEB-INF/lib
(if the direcory already exists).*) The zip file may contain .jar files which are already present in the WEB-INF/lib
folder of your webapps.
Multiexcerpt | ||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||
The Swagger API explorer tool searches for the API at a path set in
When using one of Magnolia's preconfigured bundles running on localhost, set the property to 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
After setting the base path, restart Magnolia. Swagger is in Dev > REST Tools. |
Anchor | ||||
---|---|---|---|---|
|
This section provides a step by step series of instructions to setup a Magnolia bundle which contains all REST modules inclusing magnolia-rest-tools
to use the swagger UI tools. The procedure is using the Magnolia CLI. If you are an experienced Magnolia user, you can skipt this and setup Magnolia by your prefered style.
Expand | ||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||
#1 Get the shell and choose a directory to work withOpen a shell and change to directory of your choice. In our example, we use the directory
#2 Downloading a bundle with CLI jumpstart
Jumpstart downloads and extracts the latest version of Jumpstart also sets the property When the execution of jumpstart is done, your directory looks like this:
We will need the #3 Adding the magnolia-rest tools to the bundleDownload the Rest tools bundle
~/dev/mgnl-rest-test-base/apache-tomcat/webapps/magnoliaAuthor/WEB-INF/lib . Some of the files may already be there, that's fine.#4 Start MagnoliaYou are ready to start Magnolia - actually the Tomcat server - for the first time. Go to our "root" directory ans start with the CLI command
Give Magnolia some time. On the first start up Magnolia installs some configurations for a bunch of modules, etc. pp. #5 Login on the author contextOpen your favorite browser, open the URL http://localhost:8080/magnoliaAuthor/ and login as user #6 Set the swagger base api pathIn order to properly use the swagger UI tools - which are used for development only - we must adapt one property in the configuration. On the UAdmin - open the Configuration app and open the node Open the folder This property is one of the rare one which requires a server restart to make the change effective. #7 Restart MagnoliaGo to the shell where you have started Magnolia. To stop the server - press Now start it again:
|
Anchor | ||||
---|---|---|---|---|
|
Note | ||||||
---|---|---|---|---|---|---|
Please read and understand REST security before enabling and using the REST endpoints on a productive environment. |
In the context of this tutorial to get started, you will use users with roles provided by the default setup of the the Magnolia bundle.
superuser
on the author context - for testing reasons only!On the author context use the superuser is granted:
/
on every JCR workspace - granted by the role superuser
.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!
anonymous
user on the public contextThe public context typically is visited by users which do not authenticate. Nevertheless, such visits are done as anonymous
user - which also has some permissions.
On the public context anonymous user is granted:
/
for the JCR workspaces website
, dam
, googleSitemaps
, category
, tours
Mgnl get |
---|
/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.
On a productive environment - we highly recommend to create custom REST roles granting specific access for specific use cases.
Anchor | ||||
---|---|---|---|---|
|
..
...
..