Page History

HTML Wrap

align	right
class	menu

Page properties

Download

Multiple submodules

Edition

CE, Cloud

License

Include Page

	_MLA
	_MLA

,

Include Page

	_GPL
	_GPL

Issues

MGNLREST

Maven site

REST

Latest version

Artifact resource link

groupId	info.magnolia.rest
artifactId	magnolia-rest
label	$version
renderType	display_only
resourceType	JAR

HTML Wrap

clear	both
width	244px
align	right
class	menu

Modules

Multiexcerpt

MultiExcerptName	JAX-RS-basics-and-dependencies

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.

Advanced Tables - Table Plus

enableHeadingAttributes	false
enableSorting	false
class	m5-configuration-tree
enableHighlighting	false

Node name

Value

Mgnl f

modules

Mgnl f

rest-services

Mgnl f

rest-endpoints

Mgnl n

commands

Mgnl n

nodes

Mgnl p

class

info.magnolia.rest.service.node.definition.ConfiguredNodeEndpointDefinition

Mgnl p

implementationClass

info.magnolia.rest.service.node.v1.NodeEndpoint

Mgnl n

properties

REST Integration

Multiexcerpt

MultiExcerptName	rest-integration-module-description

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.

Advanced Tables - Table Plus

enableHeadingAttributes	false
enableSorting	false
class	m5-configuration-tree
enableHighlighting	false

Node name

Value

Mgnl f

modules

Mgnl f

rest-integration

Mgnl f

config

Mgnl n

additionalProviders

Mgnl n

restExceptionMapper

Mgnl p

providerClass

info.magnolia.rest.RestExceptionMapper

Mgnl n

restJacksonDelegateProvider

Mgnl p

providerClass

info.magnolia.resteasy.client.components.RestEasyDelegateJacksonProvider

Mgnl n

apiListingResource

Mgnl p

providerClass

io.swagger.jaxrs.listing.ApiListingResource

Mgnl n

swaggerSerializers

Mgnl p

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.

Advanced Tables - Table Plus

enableHeadingAttributes	false
enableSorting	false
class	m5-configuration-tree
enableHighlighting	false

Node name

Value

Mgnl f

modules

Mgnl f

rest-content-delivery

Mgnl n

version

2.0.0

REST Tools

Multiexcerpt

MultiExcerptName	rest-tools-module-description

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.

Not installed by default.

Installing

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

Artifact maven dependencies snippet

groupId	info.magnolia.rest
artifactId	magnolia-rest-services

Artifact maven dependencies snippet

groupId	info.magnolia.rest
artifactId	magnolia-rest-integration

Artifact maven dependencies snippet

groupId	info.magnolia.rest
artifactId	magnolia-rest-content-delivery

Artifact maven dependencies snippet

groupId	info.magnolia.rest
artifactId	magnolia-rest-tools

Include Page

	_Pre-built jars are also available
	_Pre-built jars are also available

Artifact resource link
groupId info.magnolia.rest
artifactId magnolia-rest-services
label $artifactId.jar
renderType download_link
resourceType JAR
Artifact resource link
groupId info.magnolia.rest
artifactId magnolia-rest-integration
label $artifactId.jar
renderType download_link
resourceType JAR
Artifact resource link
groupId info.magnolia.rest
artifactId magnolia-rest-content-delivery
label $artifactId.jar
renderType download_link
resourceType JAR
Rest Tools bundle:
Artifact resource link
groupId info.magnolia.rest
artifactId magnolia-rest-tools
label $artifactId.zip
renderType download_link
resourceType ZIP

Info
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

Multiexcerpt

MultiExcerptName	setting-swagger-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:

Code Block

language	erl

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

Advanced Tables - Table Plus

enableHeadingAttributes	false
enableSorting	false
class	m5-configuration-tree
enableHighlighting	false

Node name

Value

Mgnl f

modules

Mgnl f

rest-tools

Mgnl f

config

Mgnl p

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

Note
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:

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

Advanced Tables - Table Plus

enableHeadingAttributes	false
enableSorting	false
class	m5-configuration-tree
enableHighlighting	false

Node name

Value

Mgnl f

modules

Mgnl f

rest-services

Mgnl f

rest-endpoints

Mgnl n

commands

Mgnl n

enabledCommands

Mgnl n

activate

Mgnl n

access

Mgnl n

roles

Mgnl p

rest

rest-admin

Mgnl p

catalogName

website

Mgnl p

commandName

activate

Mgnl n

markAsDeleted

Mgnl n

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

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

Localtab Group

Localtab

active	true
title	YAML file

Code Block

language	yaml
title	restEndpoints/my-endpoint.yaml

class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
workspace: website
depth: 2
includeSystemProperties: false
nodeTypes:
  - mgnl:page
childNodeTypes:
  - mgnl:area
  - mgnl:component
#references

Localtab

title	JCR node

Advanced Tables - Table Plus

heading	0
multiple	false
enableHeadingAttributes	false
enableSorting	false
class	m5-configuration-tree
enableHighlighting	false

Node name

Value

Mgnl f

restEndpoints

Mgnl n

my-endpoint

Mgnl p

class

info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition

Mgnl p

workspace

website

Mgnl p

depth

2

Mgnl p

includeSystemProperties

false

Mgnl n

nodeTypes

Mgnl p

0

mgnl:page

Mgnl n

childNodeTypes

Mgnl p

0

mgnl:area

Mgnl p

1

mgnl:component

For a complete reference - please see Delivery endpoint API v2 - Configuration.

Security

See REST security.

Page tree

Versions Compared

Old Version 2

New Version 3

Key

Modules

REST Services

REST Integration

REST Content Delivery

REST Tools

Installing

Configuration

REST Tools module - Setting the API base path

REST Services module - configuring the commands endpoint

Content Delivery module - configuring the delivery endpoint

Security