REST module

The information on this documentation page is not yet applicable in production.

Edition

CE

License

MLA, GPL

Issues

MGNLREST

Git

Modules / rest

Maven site

REST

Latest

3.0-SNAPSHOT

Magnolia’s REST Web service allows you to manipulate content through a Web API. You can create, read, update and delete content nodes. 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

The preconfigured Magnolia bundles contain the magnolia-rest-services, magnolia-rest-integration and magnolia-rest-content-delivery modules but not magnolia-rest-tools.

REST Services

The REST Services module installs the following endpoints:

  • nodes

  • properties

  • commands

  • import

  • status

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.

  • For cloud environments, installs a delivery service and an HTTP servlet request decorator.

  • Lets you define additional providers or marshallers 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 Content Delivery

The REST Content Delivery module provides a generic DeliveryEndpointDefinition that lets you configure delivery endpoints for specific content sources.

This module depends on the rest-integration module.

REST Tools

The REST Tools module provides:

  • an API-aware dispatcher of REST requests to dynamically registered endpoints.

  • an API-aware environment-bound delivery service useful for (un)registering Swagger endpoints.

  • the Magnolia REST Tools app.

REST Tools app

The Magnolia REST Tools app makes use of the Swagger UI that allows you to visualize and interact with the API’s resources without having any of the implementation logic in place.

Swagger UI’s index.html reads the apiBasepath from a GET parameter, provided by the app. The UI is further edited to match the Magnolia 6 UI theme, hide Swagger’s top-bar, as well as to expand tags and organize them first.

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-integration</artifactId>
  <version>3.0-SNAPSHOT</version>
</dependency>
<dependency>
  <groupId>info.magnolia.rest</groupId>
  <artifactId>magnolia-rest-services</artifactId>
  <version>3.0-SNAPSHOT</version>
</dependency>
<dependency>
  <groupId>info.magnolia.rest</groupId>
  <artifactId>magnolia-rest-tools</artifactId>
  <version>3.0-SNAPSHOT</version>
</dependency>
<dependency>
  <groupId>info.magnolia.rest</groupId>
  <artifactId>magnolia-rest-content-delivery</artifactId>
  <version>3.0-SNAPSHOT</version>
</dependency>
<dependency>
  <groupId>info.magnolia.rest</groupId>
  <artifactId>magnolia-rest-norsu-delivery</artifactId>
  <version>3.0-SNAPSHOT</version>
</dependency>
<dependency>
  <groupId>info.magnolia.rest</groupId>
  <artifactId>magnolia-rest-jcr-delivery</artifactId>
  <version>3.0-SNAPSHOT</version>
</dependency>

Configuration

Delivery endpoint

For a complete reference, please see the Delivery API page.

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.

    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.

API base path

The API base path is needed to point the static Swagger UI to the exposed openapi.json.

The Swagger API explorer tool searches for the API at a path set in /modules/rest-tools/config/apiBasepath. The value for this property must match the following pattern:

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

The default value is http://localhost:8080/.rest.

On localhost

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.

Usage

For usage, see the Delivery API page.

Feedback

DX Core

×

Location

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

You are currently perusing through the REST module docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules