REST module

Developer productivity Bundled: Framework

Edition

CE

License

MLA, GPL

Issues

MGNLREST

Maven site

REST

Latest

3.0.0

REST

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 publish, export and import content.

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 uses RESTeasy for this purpose.

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

Magnolia’s REST web services consist of several modules:

  • REST Services

  • REST Integration

  • REST Content Delivery

  • REST Tools

REST Services

The REST Services module installs the following endpoints of the REST API: nodes, properties and commands.

REST Services nodes

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>/restEndpoints for any custom 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 integration

REST Content Delivery

The REST Content Delivery module lets you configure a content delivery endpoint with minimal overhead.

The delivery endpoint allows you to get JCR content through a RESTful API. The nodes can be pages, components, stories or anything else that is stored in a workspace. The response is displayed in a concise JSON format.

This module depends on the rest-integration module.

REST Integration module node

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.

This is installed by default.

Installing with Maven

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

<dependency>
  <groupId>info.magnolia.rest</groupId>
  <artifactId>magnolia-rest-services</artifactId>
  <version>3.0.0</version> (1)
</dependency>
1 Should you need to specify the module version, do it using <version>. 
<dependency>
  <groupId>info.magnolia.rest</groupId>
  <artifactId>magnolia-rest-integration</artifactId>
  <version>3.0.0</version> (1)
</dependency>
1 Should you need to specify the module version, do it using <version>. 
<dependency>
  <groupId>info.magnolia.rest</groupId>
  <artifactId>magnolia-rest-content-delivery</artifactId>
  <version>3.0.0</version> (1)
</dependency>
1 Should you need to specify the module version, do it using <version>. 
<dependency>
  <groupId>info.magnolia.rest</groupId>
  <artifactId>magnolia-rest-tools</artifactId>
  <version>3.0.0</version> (1)
</dependency>
1 Should you need to specify the module version, do it using <version>.
Preconfigured Magnolia bundles contain the magnolia-rest-services, magnolia-rest-integration and magnolia-rest-content-delivery modules but not magnolia-rest-tools.

Configuration

REST Tools module - 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.

!REST Content Delivery node

After setting the base path, restart Magnolia.

Swagger is in Dev > REST Tools.

Swagger

REST Services module - configuring the commands endpoint

You can make sweeping changes with commands, such as bypassing approval and deleting the whole site. Commands are therefore subject to special security restrictions.

To enable the use of commands through REST:

  1. In the Security app, grant URI access permission to the path /.rest/commands/v2/* to the role for users who need access to the commands endpoint.

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

REST Services module - configuring the commands endpoint

Property Description

enabledCommands

required

Enabled commands node.

     <command>

required

Arbitrary name for the command. Use any name you like.

         access

required

Access node.

             roles

required

Roles node.

                 <role>

required

Role name. Grants the role permission to execute the command. Add the rest-admin role. The property name is arbitrary but the value must be a valid role name.

         catalogName

required

Catalog where the command resides.

         commandName

required

Command definition name.

Content Delivery module - configuring the delivery endpoint

You can define multiple endpoints in the version 2 of the delivery endpoint, definitions can be in YAML or in JCR ( on the configuration workspace).

Every endpoint is accessible via distinct endpointPath. The endpointPath property is set automatically by the given name and location of the endpoint definition, or it can be set explicitly in the configuration.

<magnolia-base-path>/.rest/endpointPath/{path}
<magnolia-base-path>/.rest/endpointPath?query-parameters

restEndpoints/my-endpoint.yaml
$type: jcrDeliveryEndpoint_v2
workspace: website
depth: 2
nodeTypes:
  - mgnl:page
childNodeTypes:
  - mgnl:area
  - mgnl:component
#references
For a complete reference - please see Delivery API - Configuration.

Security

See REST security.

Related topics
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules