Magnolia 5.4 reached end of life on November 15, 2018. This branch is no longer supported, see End-of-life policy.
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.
Try the My first REST request tutorial.
By default, the REST API requires authentication. Authenticate by passing a valid username and password with your request.
curl --user superuser:superuser http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/travel
The username you pass must have a permission to issue requests to the endpoints. To grant the permission, assign the rest
role to the user.
Anonymous REST access is also possible but not configured by default. It is common to permit GET requests to some endpoints at certain paths, for example to use the REST API as a content provider for an AngularJS app that consumes content as JSON. To grant anonymous access, we recommend that you create a more limited rest-anonymous
role that only grants GET permission to the relevant endpoint and path, then assign the new role to the anonymous
user.
When you use the Swagger API explorer you are already logged into Magnolia. Any requests made in Swagger are executed with the permissions of the currently logged-in account.
Permissions to issue REST requests are controlled using Magnolia's standard role-based security mechanism.
The REST module installs a rest
role which has the permission to issue requests to the nodes
and properties
endpoints by default.
Web access
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* |
Get & Post | /.rest/cache/v1* |
Get & Post | /.rest/api-docs* |
Configured access
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 |
The 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.
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.
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.
To enable the use of commands through REST:
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 |
---|---|
modules |
|
rest-services |
|
rest-endpoints | |
commands |
|
enabledCommands |
|
activate |
|
access |
|
roles |
|
rest | rest |
catalogName | website |
commandName | activate |
markAsDeleted |
|
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 default |
| required Catalog where the command resides. |
| required Command definition name. |
The REST API has three endpoints: nodes
, properties
and commands
. You can read, create, update and delete content by issuing requests to the endpoints.
/nodes/v1/{workspace}/{path} |
Returns a node from the specified workspace and path. Example: Reading content
Parameter | Default value | Description | Parameter type | Data type |
|
|
|
| |
|
|
|
|
|
|
| Depth of child nodes to include. 0 is just the node. 1 is node and its children etc. |
|
|
|
| List of node types to exclude |
|
|
|
|
|
|
|
/nodes/v1/{workspace}/{path} |
Creates a node and adds passed properties. Example: Creating content
You can add only one node per request. You can not put nested nodes.
Parameter | Description | Parameter type | Data type |
|
|
| |
|
|
|
|
| Request body in JSON or XML format |
|
|
/nodes/v1/{workspace}/{path} |
Updates a node by adding passed properties. Example: Updating content
Parameter | Description | Parameter type | Data type |
|
|
| |
|
|
|
|
| Request body in JSON or XML format |
|
|
/nodes/v1/{workspace}/{path} |
Deletes a node.
Parameter | Description | Parameter type | Data type |
|
|
| |
|
|
|
|
/properties/v1/{workspace}/{path} |
Reads a property from a node.
Parameter | Description | Parameter type | Data type |
|
|
| |
|
|
|
|
Example: Get the siteTitle
property of the travel site
http://localhost:8080/magnoliaAuthor/.rest/properties/v1/website/travel/siteTitle
/properties/v1/{workspace}/{path} |
Adds a property on a node.
Parameter | Default value | Description | Parameter type | Data type |
|
|
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Indicates if the property should be a multivalue property. |
|
|
/properties/v1/{workspace}/{path} |
Updates a property on a node.
Parameter | Default value | Description | Parameter type | Data type |
|
|
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Indicates if the property should be a multivalue property. |
|
|
/properties/v1/{workspace}/{path} |
Deletes a property.
Parameter | Description | Parameter type | Data type |
|
|
| |
|
|
|
|
/commands/v2/{catalogName}/{commandName} |
Executes a command in a catalog.
Parameter | Default value | Description | Parameter type | Data type |
|
|
|
| |
|
|
|
| |
|
| Request body in JSON or XML format |
|
|
/commands/v2/{commandName} |
Executes a command in the default
catalog.
Parameter | Default value | Description | Parameter type | Data type |
|
|
|
| |
|
| Request body in JSON or XML format |
|
|
Learn to create and publish a page in a few steps with My first REST request.
Read content by issuing a GET request to the nodes
or properties
endpoint.
For a JSON request, provide an HTTP request header field. You can do this using JavaScript or with cURL.
<!-- Request JSON --> curl -H "Accept: application/json" http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/travel/about \ -u superuser:superuser <!-- Request XML --> http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/travel/about
Response representation of /travel/about page:
{ "name":"about", "type":"mgnl:page", "path":"/travel/about", "identifier":"808ebe4c-72b2-49f1-b9f7-e7db22bce02f", "properties":[ { "name":"hideInNav", "type":"Boolean", "multiple":false, "value":[ "false" ] }, { "name":"title", "type":"String", "multiple":false, "value":[ "About" ] }, { "name":"title_de", "type":"String", "multiple":false, "value":[ "Über uns" ] } ], "node":null }
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <node> <identifier>808ebe4c-72b2-49f1-b9f7-e7db22bce02f</identifier> <name>about</name> <path>/travel/about</path> <properties> <property> <multiple>false</multiple> <name>hideInNav</name> <type>Boolean</type> <values> <value>false</value> </values> </property> <property> <multiple>false</multiple> <name>title</name> <type>String</type> <values> <value>About</value> </values> </property> <property> <multiple>false</multiple> <name>title_de</name> <type>String</type> <values> <value>Über uns</value> </values> </property> </properties> <type>mgnl:page</type> </node>
Create content by issuing a PUT request to the nodes
or properties
endpoint.
curl http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/travel \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -X PUT \ --user superuser:superuser \ --data \ '{ "name": "hello", "type": "mgnl:page", "path": "/travel/hello", "properties": [ { "name": "title", "type": "String", "multiple": false, "values": [ "Hello REST" ] }, { "name": "mgnl:template", "type": "String", "multiple": false, "values": [ "travel-demo:pages/standard" ] } ] }'
cURL is a command-line tool that you can use to make REST requests. It also shows the response from the API. You can even script longer requests.
Before uploading an asset via REST, make sure that the role assigned to the uploading user grants permissions to post data to the dam
workspace!
Now create an asset by issuing PUT requests to the nodes
endpoint. This requires two calls: the first creates the asset node and the second adds the binary data.
cURL command to create the asset node:
curl http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/dam \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -X PUT \ --user superuser:superuser \ --data \ '{ "name": "logo", "type": "mgnl:asset", "path": "/logo", "properties": [ { "name": "type", "type": "String", "multiple": false, "values": [ "png" ] }, { "name": "name", "type": "String", "multiple": false, "values": [ "logo" ] }, { "name": "type", "type": "String", "multiple": false, "values": [ "png" ] } ] }'
To upload the binary data, you must convert it into a String. When working with JSON, Base64 is a good format. (If you want to decode an image quickly, use an online tool such as Base64 Image).
cURL command to upload the binary node:
curl http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/dam/logo \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -X PUT \ --user superuser:superuser \ --data \ '{ "name": "jcr:content", "type": "mgnl:resource", "path": "/logo/jcr:content", "properties": [ { "name": "jcr:data", "type": "Binary", "multiple": false, "values": [ "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAFUlEQVQImWNs2Lz/PwMaYEIXoIIgAC8/AvuJXQkXAAAAAElFTkSuQmCC......" ] }, { "name": "height", "type": "Long", "multiple": false, "values": [ "5" ] }, { "name": "width", "type": "Long", "multiple": false, "values": [ "5" ] }, { "name": "extension", "type": "String", "multiple": false, "values": [ "png" ] }, { "name": "fileName", "type": "String", "multiple": false, "values": [ "logo.png" ] }, { "name": "jcr:mimeType", "type": "String", "multiple": false, "values": [ "image/png" ] } ] }'
Uploading binary data manually with cURL is a cumbersome process, but you may want to use the REST API programmatically. Before doing so, test the endpoints with cURL or with swagger. When using cURL in the shell, be aware that every shell has an upper limit on the amount of characters per line. If you try to upload big images with cURL, you may have to split the Base64 decoded data into several lines with backslashs (\
).
Update content by issuing a POST request to the nodes
or properties
endpoint.
curl http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/travel/hello \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -X POST \ -v \ --user superuser:superuser \ --data \ '{ "properties": [ { "name": "title", "type": "String", "values": [ "Hello REST updated" ] } ] }'
Publish (activate) content by issuing a POST request to the commands
endpoint.
curl http://localhost:8080/magnoliaAuthor/.rest/commands/v2/website/activate \ -H "Content-Type: application/json" \ -X POST --user superuser:superuser \ --data \ '{ "repository": "website", "path": "/travel/hello", "recursive": "false" }'
Delete content by issuing a POST request to the commands
endpoint. Magnolia provides delete commands that unpublish the content first and then delete it.
curl http://localhost:8080/magnoliaAuthor/.rest/commands/v2/default/delete \ -H "Content-Type: application/json" \ -X POST --user superuser:superuser \ --data \ '{ "repository": "website", "path": "/travel/hello", "recursive": "false" }'
The delete
command is not configured or enabled by default for security reasons. You must configure and enable the command on the configuration /modules/rest-services/rest-endpoints/commands/enabledCommands
.
You can also delete content by issuing a DELETE request to a node or property. However, this is not a good idea if the content is already published. A DELETE request will only delete the node from the author instance, not from public instances.
curl http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/travel/hello \ -H "Content-Type: application/json" \ -X DELETE --user superuser:superuser
Once you learn the basics with Swagger, try making requests with cURL.
The Web services are versioned. The version number is built into the service URI between the service path and the method name:
/.rest/nodes/v1/website/travel
Versioning provides backwards compatibility. Any calls you write against version 1 will continue to work when Magnolia upgrades the API to version 2. The version numbering scheme goes v1, v2, v3 and so on. Commands were upgraded to v2. in 5.5.4+
Correspondingly, Java endpoints are placed in *.v1, packages:
info.magnolia.rest.service.node.v1 info.magnolia.rest.service.property.v1 info.magnolia.rest.service.command.v2
Java endpoints contain only code that is necessary to expose the Web services. Service logic goes into service implementations. For example, CommandEndpoint delegates to CommandsManager (its service).
To expose your own service endpoint:
/modules/<your-module>/rest-endpoints
.class
property to your definition class.implementationClass
property to your implementation class.Example: Rest-endpoint configuration in /modules/rest-services/rest-endpoints/nodes
.
Node name | Value |
---|---|
modules |
|
rest-services |
|
rest-endpoints |
|
nodes |
|
class | info.magnolia.rest.service.node.definition.ConfiguredNodeEndpointDefinition |
implementationClass | info.magnolia.rest.service.node.v1.NodeEndpoint |
Properties
rest-endpoints | required Rest endpoints folder. |
| required Nodes API node. |
| required Definition class. |
| required Implementation class. |
Your endpoint is available at:
http://<domain>[:<port>]/<contextPath>/.rest/<endpoint>/<version>/{node}/{edge}
Here is a request URL to the nodes API. The endpoint is nodes
and the edge is the workspace/path.
http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/travel