Magnolia 5.4 reached end of life on November 15, 2018. This branch is no longer supported, see End-of-life policy.
My first REST request and REST API show you how to make requests to Magnolia's REST API. This document is about the REST module.
Magnolia's REST Web service allows you to manipulate content through a Web API. You can create, read, update and delete nodes in the JCR. The nodes can be pages, components, contacts or anything else that is stored in a named workspace. You can also execute commands to activate, export and import content.
The REST service is similar to the Data module in Magnolia 4.5 which pulled data from other sources into Magnolia. However, REST works with the push principle where your application communicates with a Magnolia REST endpoint and exchanges a representation of a resource such as an XML of a page. REST is useful for connection tasks. Use REST to push product data from a third party system into Magnolia and let editors enrich it in a Magnolia app, for example.
Modules
Magnolia's REST Web services consist of three modules.
REST Services
This module installs the endpoints of the REST API: node, property and command.
| Node name | Value |
|---|---|
modules |
|
rest-services |
|
rest-endpoints |
|
commands |
|
nodes |
|
class | info.magnolia.rest.service.node.definition.ConfiguredNodeEndpointDefinition |
implementationClass | info.magnolia.rest.service.node.v1.NodeEndpoint |
properties |
|
REST Integration
The REST Integration module installs the integration part of REST. The module:
- Monitors
/config/<module-name>/rest-endpointsfor any new endpoints you want to register. The monitoring mechanism is the same as used for observing registered dialogs, templates and apps. - Installs a special servlet
RestDispatcherServletwhich dispatches requests to the individual endpoints registered in configuration. - Lets you define additional providers or marshallers (called
MessageBodyWorkersin RESTeasy) you might need. The providers are responsible for translating the return object into JSON/XML and vice-versa. - Installs the default
restrole that initially prevents access to unauthorized requests.
| Node name | Value |
|---|---|
modules |
|
rest-integration |
|
config |
|
additionalProviders |
|
restExceptionMapper |
|
providerClass | info.magnolia.rest.RestExceptionMapper |
apiDeclarationProvider |
|
providerClass | com.wordnik.swagger.jaxrs.listing.ApiDeclarationProvider |
resourceListingProvider |
|
providerClass | com.wordnik.swagger.jaxrs.listing.ResourceListingProvider |
REST Tools
The REST Tools module extends the RestDispatcherServlet with a custom, API-aware servlet that can read API annotations from all available REST endpoints. The servlet enables the endpoints in the Swagger API explorer. If you write your own endpoint you need to add annotations in the code yourself. 
Not installed by default.
Installing
Maven is the easiest way to install the modules. Add the following dependencies to your bundle:
Pre-built jars are also available for download. See Installing a module for help.
Preconfigured Magnolia bundles contain the modules magnolia-rest-services and magnolia-rest-integration but not magnolia-rest-tools. When adding magnolia-rest-tools directly to your bundle, please unpack the zip file and add all its files to WEB-INF/libs of your webapps.
Configuration
Setting the API 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:
<protocoll>://<hostname>:<port>/<context>/.rest
When using one of Magnolias 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.
| Node name | Value |
|---|---|
modules |
|
rest-tools |
|
config |
|
apiBasepath | http://localhost:8080/magnoliaAuthor/.rest |
After setting the base path, restart Magnolia.
Swagger is in Dev > REST Tools.
Security
Permissions to issue REST requests are controlled using Magnolia's standard role-based security mechanism. The REST module installs a Web access Configured access The Commands are custom actions executed at pre-defined trigger points. Magnolia uses commands to activate content, send email, flush the cache, take backups, import and export data, and to do many other tasks. Commands can perform duties within the system or connect to external resources. To enable the use of commands through REST: modules rest-services rest-endpoints commands enabledCommands activate access roles rest rest catalogName website commandName activate markAsDeleted Properties: required Enabled commands node. required Arbitrary name for the command. Use any name you like. required Access node. required Roles node. required Role name. Grants the role permission to execute the command . Add the default required Catalog where the command resides. required Command definition name.rest role
rest role which has the permission to issue requests to the nodes and properties endpoints by default.Permission Path Deny /.rest*Deny /.rest/commands*Deny /.rest/nodes*Get & Post /.rest/nodes/v1/website*Deny /.rest/properties*Get & Post /.rest/properties/v1/website*Get & Post /.rest/cache/v1*Get & Post /.rest/api-docs*Applies to Name Path Commands Delete /modules/rest-services/rest-endpoints/commands/enabledCommands/markAsDeleted/access/rolesActivate /modules/rest-services/rest-endpoints/commands/enabledCommands/activate/access/rolessuperuser account has the rest role by default so you can use superuser to test your requests. However, for production use you should create a dedicated account for REST. The anonymous account is specifically denied access to the REST endpoints.Enabling commands (optional)
You can make sweeping changes with commands, such as bypassing approval and deleting the whole site. Commands are therefore subject to a special security restrictions. rest role a permission to the issue requests to the commands endpoint. Permission to the endpoint is denied by default. Add a new rule.
/modules/rest-services/rest-endpoints/commands/enabledCommands.Node name Value enabledCommands<command>accessroles<role>rest role. The property name is arbitrary but the value must be a valid role name.catalogNamecommandName
Uninstalling
To uninstall a module, remove the module JAR file from the /WEB-INF/lib folder and restart Magnolia.
However, this is rarely enough. Modules add and modify configuration during installation. The use of a module also changes content. Removing all of these changes is difficult without knowing the installation tasks in detail.
To test a module, use the embedded Derby database and take a backup of your repositories folder. Install the module and try it. When you are done testing, remove the module JAR and restore the repositories folder from the backup. This way you can go back to square one.
We also recommend that you segregate the development and production environments. Take regular backups for disaster recovery so you can revert to a prior state in a routine fashion.
Overview
Content Tools