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 nameValue

 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. It monitors /config/<module-name>/rest-endpoints for any new endpoints you want to register. The monitoring mechanism is the same as used for observing registered dialogs, templates and apps. The module also installs a special servlet RestDispatcherServlet which dispatches requests to the individual endpoints registered in configuration. The Integration module also allows lets you define additional providers or marshallers (called MessageBodyWorkers in RESTeasy) you might need. The providers are responsible for translating the return object into JSON/XML and vice-versa. Lastly, the Integration module installs the default rest role that initially prevents access to unauthorized requests.

Node nameValue

 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. (warning) Not installed by default. Download the REST Tools bundle to get all the third-party JARs REST depends on.

Download

REST is a Community Edition module. The Services and Integration submodules are typically already installed but you need to install the Tools module yourself. You can download all the modules from Magnolia's Nexus repository. Download the REST Tools bundle to get all the third-party JARs REST depends on.

Installing

(warning) Create a backup of your system before you install a module. Uninstalling a module is not as simple as removing the .jar file. Modules add and change configurations and may change the content. Try new modules in a test environment first. A module consists of a JAR file and may include dependent JAR files. Modules are responsible for updating their own content and configurations across versions. Be sure to keep only one version of each module and its dependencies.

To install a module:

  1. Stop the application server.
  2. Copy the module JAR files into the WEB-INF/lib directory. The location of this directory depends on the application server.
    • Tomcat: /webapps/magnoliaAuthor/WEB-INF/lib
    • JBoss: /server/default/deploy/magnoliaAuthor/WEB-INF/lib
  3. Restart the server.
  4. Go to the AdminCentral URL.
  5. Start the Web update process.
  6. Click Start up Magnolia.

Repeat the steps for each author and public instance.

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 which is probably not correct. 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 nameValue

 modules


 rest-tools


 config


 apiBasepath

http://localhost:8080/magnoliaAuthor/.rest

After setting the base path, restart Magnolia.

Swagger is in Dev > REST Tools.

 Screenshot for 1.2


Security

Permissions to issue REST requests are controlled using Magnolia's standard  role-based security mechanism .

rest role

The REST module installs a rest role which has the permission to issue requests to the nodes and properties endpoints by default.

Access control lists

WorkspacePermissionScopePath
UserrolesRead onlySelected/rest

Web access

PermissionPath
Deny/.rest*
Deny/.rest/commands*
Deny/.rest/nodes*
Get & Post/.rest/nodes/v1/website*
Deny/.rest/properties*
Get & Post/.rest/properties/v1/website*

Configured access

Applies toNamePath
CommandsDelete/modules/rest-services/rest-endpoints/commands/enabledCommands/markAsDeleted/access/roles

Activate
/modules/rest-services/rest-endpoints/commands/enabledCommands/activate/access/roles

The superuser 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

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.

(warning) 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. 

To enable the use of commands through REST:

  1. Open the security app and grant the rest role a permission to the issue requests to the commands endpoint.  Permission to the endpoint is denied by default. Add a new rule.

  1. fake
  2. Whitelist any commands you want to expose to REST. The white list is managed in /modules/rest-services/rest-endpoints/commands/enabledCommands.
Node nameValue

 modules

 

 rest-services

 

 rest-endpoints

 

 commands

 

 enabledCommands

 

 activate

 

 access

 

 roles

 

 rest

rest

 catalogName

website

 commandName

activate

 markAsDeleted

 

Properties

  • enabledCommands   
    • <command>  : Name for the command. Use any name you like.
      • access   
        • roles   
          • <role>  : Grants permission to execute the command to a role. Add the default role rest. The role node name is arbitrary but the value must be a valid role name.
      • catalogName  Catalog where the command resides.
      • commandName  Command definition

Uninstalling

To uninstall a module, remove the module JAR file from the /WEB-INF/lib folder and restart Magnolia.

(warning) 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.

#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))