Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.
My first REST request and REST API show you how to make requests to Magnolia's REST API. This document is about the REST module.
The REST service is similar to the Data module in Magnolia 4.5 which pulled data from other sources into Magnolia. However, REST works with the push principle where your application communicates with a Magnolia REST endpoint and exchanges a representation of a resource such as an XML of a page. REST is useful for connection tasks. Use REST to push product data from a third party system into Magnolia and let editors enrich it in a Magnolia app, for example.
Magnolia's REST Web services consist of three modules.
This module installs the endpoints of the REST API: node, property and command.
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 |
The REST Integration module installs the integration part of REST. It monitors /config/<module-name>/rest-endpoints
for any new endpoints you want to register. The monitoring mechanism is the same as used for observing registered dialogs, templates and apps. The module also installs a special servlet RestDispatcherServlet
which dispatches requests to the individual endpoints registered in configuration. The Integration module also allows 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. Lastly, the Integration module installs the default rest
role that initially prevents access to unauthorized requests.
Node name | Value |
---|---|
modules | |
rest-integration | |
config | |
additionalProviders | |
restExceptionMapper | |
providerClass | info.magnolia.rest.RestExceptionMapper |
apiDeclarationProvider | |
providerClass | com.wordnik.swagger.jaxrs.listing.ApiDeclarationProvider |
resourceListingProvider | |
providerClass | com.wordnik.swagger.jaxrs.listing.ResourceListingProvider |
The REST Tools 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. Download the REST Tools bundle to get all the third-party JARs REST depends on.
REST is a Community Edition module. The Services and Integration submodules are typically already installed but you need to install the Tools module yourself. You can download all the modules from Magnolia's Nexus repository. Download the REST Tools bundle to get all the third-party JARs REST depends on.
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
which is probably not correct. 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 name | Value |
---|---|
modules | |
rest-tools | |
config | |
apiBasepath | http://localhost:8080/magnoliaAuthor/.rest |
After setting the base path, restart Magnolia.
Swagger is in Dev > REST Tools.
Permissions to issue REST requests are controlled using Magnolia's standard role-based security mechanism . The REST module installs a Access control lists Web access Configured access The Commands are custom actions executed at pre-defined trigger points. Magnolia uses commands to activate content, send email, flush the cache, take backups, import and export data, and to do many other tasks. Commands can perform duties within the system or connect to external resources. To enable the use of commands through REST: modules rest-services rest-endpoints commands enabledCommands activate access roles rest rest catalogName website commandName activate markAsDeleted Propertiesrest role
rest
role which has the permission to issue requests to the nodes
and properties
endpoints by default.Workspace Permission Scope Path Userroles Read only Selected /rest
Permission Path Deny /.rest*
Deny /.rest/commands*
Deny /.rest/nodes*
Get & Post /.rest/nodes/v1/website*
Deny /.rest/properties*
Get & Post /.rest/properties/v1/website*
Applies to Name Path Commands Delete /modules/rest-services/rest-endpoints/commands/enabledCommands/markAsDeleted/access/roles
Activate /modules/rest-services/rest-endpoints/commands/enabledCommands/activate/access/roles
superuser
account has the rest
role by default so you can use superuser to test your requests. However, for production use you should create a dedicated account for REST. The anonymous
account is specifically denied access to the REST endpoints.Enabling commands
You can make sweeping changes with commands, such as bypassing approval and deleting the whole site. Commands are therefore subject to a special security restrictions.
rest
role a permission to the issue requests to the commands
endpoint. Permission to the endpoint is denied by default. Add a new rule./modules/rest-services/rest-endpoints/commands/enabledCommands
.Node name Value enabledCommands
<command>
: Name for the command. Use any name you like.access
roles
<role>
: Grants permission to execute the command to a role. Add the default role rest
. The role node name is arbitrary but the value must be a valid role name.catalogName
: Catalog where the command resides.commandName
: Command definition.