Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
Modules
The Java API for RESTful Web Services - JAX-RS is defined in the packages The dependencies (for both the interfaces and the implementations) are managed by the 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.magnolia-rest-integration
module.
- 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 name | Value |
---|---|
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:/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. RestDispatcherServlet
which dispatches requests to the individual endpoints registered in configuration.
MessageBodyWorkers
in RESTeasy) you might need. The providers are responsible for translating the return object into JSON/XML and vice-versa.rest
role that initially prevents access to unauthorized requests.
Node name | Value |
---|---|
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.
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. 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.1.8</version> </dependency>
<dependency> <groupId>info.magnolia.rest</groupId> <artifactId>magnolia-rest-integration</artifactId> <version>2.1.8</version> </dependency>
<dependency> <groupId>info.magnolia.rest</groupId> <artifactId>magnolia-rest-content-delivery</artifactId> <version>2.1.8</version> </dependency>
<dependency> <groupId>info.magnolia.rest</groupId> <artifactId>magnolia-rest-tools</artifactId> <version>2.1.8</version> </dependency>
- magnolia-rest-services.jar
- magnolia-rest-integration.jar
- magnolia-rest-content-delivery.jar
- Rest Tools bundle: magnolia-rest-tools.zip
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 When using one of Magnolia's preconfigured bundles running on localhost, set the property to 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 modules rest-tools config apiBasepath http://localhost:8080/magnoliaAuthor/.rest After setting the base path, restart Magnolia. Swagger is in Dev > REST Tools./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
http://localhost:8080/magnoliaAuthor/.rest
.
http://localhost:8080/magnoliaAuthor/.rest
.Node name Value
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:
- 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
.
Node name | Value |
---|---|
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. |
| required Arbitrary name for the command. Use any name you like. |
| required Access node. |
| required Roles node. |
| required Role name. Grants the role permission to execute the command. Add the |
| required Catalog where the command resides. |
| 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
class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition workspace: website depth: 2 includeSystemProperties: false nodeTypes: - mgnl:page childNodeTypes: - mgnl:area - mgnl:component #references
Node name | Value |
---|---|
restEndpoints | |
my-endpoint | |
class | info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition |
workspace | website |
depth | 2 |
includeSystemProperties | false |
nodeTypes | |
0 | mgnl:page |
childNodeTypes | |
0 | mgnl:area |
1 | mgnl:component |
For a complete reference - please see Delivery endpoint API v2 - Configuration.
Security
See REST security.