Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
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.
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.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.
The Swagger framework is supported by a set of core tools for designing, building, and documenting RESTful APIs. Source: https://swagger.io/tools/ Magnolia provides integration with Swagger tools directly in the Admin UI. Swagger tools are for development and testing purposes only.
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:
With a downloaded bundle
If you are running a preconfigured Magnolia Tomcat bundle:
$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.
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 http://localhost:8080/magnoliaAuthor/.rest After setting the base path, restart Magnolia. Swagger is in Dev > REST Tools./modules/rest-tools/config/apiBasepath
. The default value is
http://localhost:8080/.rest
. The value for this property must match the following pattern:<protocol>://<hostname>:<port>/<context>/.rest
http://localhost:8080/magnoliaAuthor/.rest
.
http://localhost:8080/magnoliaAuthor/.rest
.Node name Value
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.
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..
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
./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 for REST.
anonymous
user on the public context The 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
/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.
Magnolia provides out of the box the following REST endpoints:
Endpoint | HTTP methods | Swagger UI enabled | |||
---|---|---|---|---|---|
delivery | GET Read node. | - | - | - | - |
nodes | GET | PUT | POST | DELETE | ✓ |
Read node | Create node | Update node | Delete node | ||
properties | GET | PUT Create property | POST Update property | DELETE | ✓ |
Read property | Delete property | ||||
commands | - | - | POST Execute command | - | ✓ |
If you want to use REST to create, update and delete content - we recommend using the Nodes endpoint which supports all required operations. If you mainly want to read data - consider using the Delivery endpoint. It provides a very handy formatted JSON and can be customized and configured with YAML via light module. With the Commands endpoint you can trigger commands. And <TODO: Add link to: Cache endpoint> deals with cache. And you always can create ypur own custom endpoints - for inspiration see How to create a custom Java based REST endpoint.
On this section we propose some tools to test the REST API - without the need to develop a REST consuming client application. Testing your REST requests is handy when you are developing client apps and similar things which will interact with the REST endpoints.
Positive | For instance Firefox displays JSON and XML in a very well readable format. |
Negative | 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. |
Tips | If you want to test on REST resources via GET, which requires authetication (to get assigned roles not provided to Upgrade the browser with add-ons to extend its possibilities to controll the request. |
cURL
is a command line tool. It can be used on most of the well known operating systems. In this tutorial we will often test REST request via cURL.
Download | https://curl.haxx.se/download.html |
Positive | Very flexible to tailor the request (method, request headers, user credentials, etc.). Response can be further processed. |
Negative | Not everybody likes command line tools. The response is not reasy to read without further tooling. No out of the box automatic URL encoding. |
Tips | On the first atempt of a request use the 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
with the swagger UI tools, skip this section, or see above about ho to enable the swagger tools.
Positive | Seamless integrated into the Magnolia UAdmin. Comfortable to use form based interface. |
Negative | The endpoints require specific annotations to make them appear on the swagger UI tools. Delivery endpoint is not annotated and will not appear on the swagger tools. REST request is sent by the user which logged into Magnolia; cumbersome to test with different users. |
Go to Dev > REST Tools. 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 magnolia-rest-services
module (propertiesv1, commandsv2, nodesv1) and one from the cache-browser-app
(cachev1).
Click List operations or Expand operations to get the detail forms for the operations.
Here is an example for GET of the nodes
endpoint:
Enter values at least for the mandatory parameters and click the button Try it out!
.
Swagger will show the response code, the response headers and the response body:
The Delivery endpoint is the latest REST API provided by Magnolia out of the box. Use it for obtaining JCR data as JSON.
Besides security settings - you must provide YAML based configuration for the delivery endpoint - otherwise the endpoint can not serve JSON.
delivery
enpointFor the YAML based configuration of the delivery endpoint - let us create a light module.
Within the light-modules folder - which is configured with the property magnolia.resources.dir
, see above - create the following structure:
define-delivery-endpoint/ └── restEndpoints/ └── delivery-base-definition.yaml
To start with - the file delivery-base-definition.yaml
can look like this:
class: info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpointDefinition params: website: depth: 2 nodeTypes: - mgnl:page - mgnl:area - mgnl:component childNodeTypes: - mgnl:area - mgnl:component rootPath: / includeSystemProperties: false
For the time being, you should know the following things:
website
is the name of the so called "endpoint prefix" - in our case it is also the name of a JCR workspace. We will use the value of the endpoint prefix later on within the REST request URL....
..