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.
The Java API for RESTful Web Services - JAX-RS is defined in the packages
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
The REST Services module installs the following endpoints of the REST API: nodes, properties and commands.
The REST Integration module installs the integration part of REST. The module:
Manages the dependencies for the required JAX-RS libraries.
/config/<module-name>/restEndpointsfor 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
RestDispatcherServletwhich dispatches requests to the individual endpoints registered in configuration.
Lets you define additional providers or marshallers called
MessageBodyWorkersin RESTeasy) you might need. The providers are responsible for translating the return object into JSON/XML and vice-versa.
Installs the default
restrole that initially prevents access to unauthorized requests.
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
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
|This is installed by default.|
Maven is the easiest way to install the module. Add the following to your bundle:
<dependency> <groupId>info.magnolia.rest</groupId> <artifactId>magnolia-rest-services</artifactId> <version>2.2.6</version> </dependency>
<dependency> <groupId>info.magnolia.rest</groupId> <artifactId>magnolia-rest-integration</artifactId> <version>2.2.6</version> </dependency>
<dependency> <groupId>info.magnolia.rest</groupId> <artifactId>magnolia-rest-content-delivery</artifactId> <version>2.2.6</version> </dependency>
<dependency> <groupId>info.magnolia.rest</groupId> <artifactId>magnolia-rest-tools</artifactId> <version>2.2.6</version> </dependency>
Preconfigured Magnolia bundles
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:
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
After setting the base path, restart Magnolia.
Swagger is in Dev > REST Tools.
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
Enabled commands node.
Arbitrary name for the command. Use any name you like.
Role name. Grants the role permission to execute the command. Add the
Catalog where the command resides.
Command definition name.
You can define multiple endpoints in the
2 of the delivery endpoint, definitions can be in YAML or in JCR ( on
Every endpoint is accessible via distinct
The endpointPath property is set automatically by the given name and
location of the endpoint definition, or it can be set explicitly in the
class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition workspace: website depth: 2 nodeTypes: - mgnl:page childNodeTypes: - mgnl:area - mgnl:component #references
For a complete reference - please see Delivery endpoint API v2 - Configuration.
See REST security.