REST module

Modules

The Java API for RESTful Web Services - JAX-RS - is defined in the packages javax.ws.rs and  javax.xml.bind. These are interfaces and sufficient for endpoint classes during compilation. However, on runtime, when the REST resources are used, a webapp also requires implementations of the these two mentioned packages. Magnolia is using RESTeasy for this purpose.

These dependencies (for both the interfaces and the implementations) are managed by the magnolia-rest-integration module.

Magnolia's REST Web services consist of three modules.

REST Services

This module installs the endpoints of the REST API: node, property and command.

REST Integration

The REST Integration module installs the integration part of REST. The module:

• Manages the dependencies for the required JAX-RS libraries.
• 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. 
• Installs a special servlet RestDispatcherServlet which dispatches requests to the individual endpoints registered in configuration. 
• 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.
• Installs the default rest role that initially prevents access to unauthorized requests.

REST Tools

The REST Tools module integrates the swagger tools into the Admin UI. These tools ease the development and testing of REST endpoints.

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

Installing

Maven is the easiest way to install the modules. Add the following dependencies to your bundle:

<dependency>
  <groupId>info.magnolia.rest</groupId>
  <artifactId>magnolia-rest-services</artifactId>
  <version>1.2.2</version>
</dependency>

<dependency>
  <groupId>info.magnolia.rest</groupId>
  <artifactId>magnolia-rest-integration</artifactId>
  <version>1.2.2</version>
</dependency>

<dependency>
  <groupId>info.magnolia.rest</groupId>
  <artifactId>magnolia-rest-tools</artifactId>
  <version>1.2.2</version>
</dependency>

• magnolia-rest-services.jar
• magnolia-rest-integration.jar
• Rest Tools bundle for Magnolia 5.5.4+: magnolia-rest-tools-1.2.1-for-magnolia-5.5.4.zip or for previous versions: magnolia-rest-tools.zip

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:

<protocol>://<hostname>:<port>/<context>/.rest

When using one of Magnolia's 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.

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.

rest role

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

Web access

Configured access

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 (optional)

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.

 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.
   
2. Whitelist any commands you want to expose to REST. The white list is managed in /modules/rest-services/rest-endpoints/commands/enabledCommands.

Properties: