Page tree
Skip to end of metadata
Go to start of metadata

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. 

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.

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

  • Manages the dependencies for the required JAX-RS libraries.
  • Monitors /config/<module-name>/rest-endpoints 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.

Node nameValue

 modules


 rest-integration


 config


 additionalProviders


 restExceptionMapper


 providerClass

info.magnolia.rest.RestExceptionMapper

 restJacksonDelegateProvider


 providerClass

info.magnolia.resteasy.client.components.RestEasyDelegateJacksonProvider

 apiListingResource


 providerClass

io.swagger.jaxrs.listing.ApiListingResource

 swaggerSerializers


 providerClass

io.swagger.jaxrs.listing.SwaggerSerializers

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.

Node nameValue

 modules


 rest-content-delivery


 version

2.0.0

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. 

(Warnung) Not installed by default.

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>2.0</version>
</dependency>

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

<dependency>
  <groupId>info.magnolia.rest</groupId>
  <artifactId>magnolia-rest-content-delivery</artifactId>
  <version>2.0</version>
</dependency>

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

Pre-built jars are also available for download. See Installing a module for help.

Preconfigured Magnolia bundles contain the magnolia-rest-services, magnolia-rest-integration and magnolia-rest-content-delivery modules but not magnolia-rest-tools. When adding magnolia-rest-tools directly to your bundle, unpack the zip file and add all the files it contains to the WEB-INF/libs folder of your webapps.

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 .

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.


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.
Node nameValue

 modules


 rest-services


 rest-endpoints


 commands


 enabledCommands


 activate


 access


 roles


 rest

rest-admin

 catalogName

website

 commandName

activate

 markAsDeleted


 backup


Properties:

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

The delivery endpoint requires a YAML configuration; otherwise, it cannot deliver content. Version 2.0 of the magnolia-rest-content-delivery module can have only one configuration. You can decorate the definition. Future versions will allow multiple configurations which can be distinguished via a URL parameter.

Add the configuration to the restEndpoints folder in a light module or within src/main/resources/<module-name>/restEndpoints in a Magnolia Maven module.

Basic configuration

my-lightmodule/restEndpoints /my-endpoint.yaml
class: info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpointDefinition
params:
  website:
    depth: 2
    nodeTypes:
      - mgnl:page
      - mgnl:area
      - mgnl:component
    childNodeTypes:
      - mgnl:area
      - mgnl:component
    rootPath: /
  trips:
    workspace: tours
    includeSystemProperties: false

Properties:

class

required

Must be info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpointDefinition or a subclass.

implementationClass

optional default=info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpoint

Must be info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpoint or a subclass.

params

required

The map defining at least one or more endpoint prefixes.

<endpointPrefix>

required

Defines an endpoint prefix where requests will be routed and handled according to the associated workspace parameters below.

The value can be an arbitrary name (no special characters!) - or it can be a real workspace name. If it is not a real workspace name, you must provide the sub property workspace.

workspace

optional

The name of the JCR workspace to deliver content from.

Must be set if the parent <endpointPrefix> is not a real workspace name.

nodeTypes

optional, default is mgnl:content

A list of allowed node types for depth-0 nodes. mgnl:folder is ignored deliberately.

childNodeTypes

optional default is mgnl:contentNode

A list of allowed node types for child nodes.

depth

optional, default is 0

The depth of child nodes to display in the result.

includeSystemProperties

optional, default is true

Specifies whether the result should show system properties.

rootPath

optional

The root path of this endpoint.

The path information when requesting the endpoint is added to this path.

bypassWorkspaceAcls

optional, default is false

If set to true , JCR security is bypassed. Use this with care and for development reasons only!

limit

optional, default is 10

The number of nodes (of level 0) in the result. Used only in the queryNodes method.

The property can be overridden when calling queryNodes with a request parameter.

Reference resolving configuration

A node may contain references to other nodes. With the references property, you can extend the configuration to force it to resolve the referenced nodes per workspace.

class: info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpointDefinition
params:
  trips:
    workspace: tours
    includeSystemProperties: false
    references:
      tour-types:
        propertyName: tourTypes
        referenceResolver:
          implementationClass: info.magnolia.rest.reference.jcr.UuidReferenceResolver
          targetWorkspace: category
Properties of references :

referencesA map which contains at least one reference definition.

<reference-name>

An arbitrary name for a ReferenceDefinition.

propertyName

The name of the JCR property which stores the reference. It can be a multi-value property.

referenceResolver

The reference resolver definition for this reference. Its definition class is ReferenceResolverDefinition.

implementationClass

A class implementing ReferenceResolverDefinition.

Current implementations: UuidReferenceResolver.

targetWorkspace

The name of the workspace where the referenced node resides.

Security

See REST security.