REST API

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

REST API reference

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 endpoint

/nodes/v1/{workspace}/{path}

Returns a node from the specified workspace and path. Example: Reading content

Parameter	Default value	Description	Parameter type	Data type
`workspace`		Workspace	`path`	`string`
`path`			`path`	`string`
`depth`	`0`	Depth of child nodes to include. 0 is just the node. 1 is node and its children etc.	`query`	`integer`
`excludeNodeTypes`		List of node types to exclude	`query`	`string`
`includeMetadata`	`false`		`query`	`boolean`

/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
`workspace`	Workspace	`path`	`string`
`path`		`path`	`string`
`body`	Request body in JSON or XML format	`body`	`string`

/nodes/v1/{workspace}/{path}

Updates a node by adding passed properties. Example: Updating content

Parameter	Description	Parameter type	Data type
`workspace`	Workspace	`path`	`string`
`path`		`path`	`string`
`body`	Request body in JSON or XML format	`body`	`string`

/nodes/v1/{workspace}/{path}

Deletes a node.

Parameter	Description	Parameter type	Data type
`workspace`	Workspace	`path`	`string`
`path`		`path`	`string`

properties endpoint

/properties/v1/{workspace}/{path}

Reads a property from a node.

Parameter	Description	Parameter type	Data type
`workspace`	Workspace	`path`	`string`
`path`		`path`	`string`

Example: Get the siteTitle property of the demo-project site

http://localhost:8080/magnoliaAuthor/.rest/properties/v1/website/demo-project/siteTitle

/properties/v1/{workspace}/{path}

Adds a property on a node.

Parameter	Default value	Description	Parameter type	Data type
`workspace`		Workspace	`path`	`string`
`path`			`path`	`string`
`name`			`query`	`string`
`value`			`query`	`array`
`type`	`String`		`query`	`string`
`multiple`		Indicates if the property should be a multivalue property.	`query`	`boolean`

/properties/v1/{workspace}/{path}

Updates a property on a node.

Parameter	Default value	Description	Parameter type	Data type
`workspace`		Workspace	`path`	`string`
`path`			`path`	`string`
`value`			`query`	`array`
`type`	`String`		`query`	`string`
`multiple`		Indicates if the property should be a multivalue property.	`query`	`boolean`

/properties/v1/{workspace}/{path}

Deletes a property.

Parameter	Description	Parameter type	Data type
`workspace`	Workspace	`path`	`string`
`path`		`path`	`string`

commands endpoint

/commands/v1/{catalogName}/{commandName}

Executes a command in a catalog.

Parameter	Default value	Description	Parameter type	Data type
`catalogName`		Command catalog	`path`	`string`
`commandName`		Command definition	`path`	`string`
`body`		Request body in JSON or XML format	`body`	`string`

/commands/v1/{commandName}

Executes a command in the default catalog.

Parameter	Default value	Description	Parameter type	Data type
`commandName`		Command definition	`path`	`string`
`body`		Request body in JSON or XML format	`body`	`string`

Examples

Learn to create and publish a page in a few steps with My first REST request .

Reading

Read content by issuing a GET request to the nodes or properties endpoint.

Read page /demo-project/about

http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/demo-project/about

Response:

JSON representation of /demo-project/about page

{
  "name":"about",
  "type":"mgnl:page",
  "path":"/demo-project/about",
  "identifier":"f312fc16-8f66-451c-bdf0-a72913b74c2d",
  "properties":[
    {
      "name":"title",
      "type":"String",
      "multiple":false,
      "values":[
        "About"
      ]
    },
    {
      "name":"sectionTitle",
      "type":"String",
      "multiple":false,
      "values":[
        "Section: About"
      ]
    },
    {
      "name":"hideInNav",
      "type":"Boolean",
      "multiple":false,
      "values":[
        "false"
      ]
    },
    {
      "name":"sectionText",
      "type":"String",
      "multiple":false,
      "values":[
        "This is the banner text for the \"About\" section. It is inherited by all child pages unless these are configured differently. A banner can be disabled in the template configuration settings."
      ]
    },
    {
      "name":"abstract",
      "type":"String",
      "multiple":false,
      "values":[
        "This is the abstract for the \"About\" page. It is a brief résumé on the content of this page. The abstract on the beginning of a page is also used in teasers and openers that reference this page. Li Europan lingues es membres del sam familie. Lor separat existentie es un myth. Por scientie, musica, sport etc, litot Europa usa li sam vocabular. Li lingues differe solmen in li grammatica, li pronunciation e li plu commun vocabules. "
      ]
    }
  ],
  "nodes":[
  ]
}

Creating

Create content by issuing a PUT request to the nodes or properties endpoint.

Create a new page /demo-project/hello

curl http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/demo-project \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -X PUT \
  --user superuser:superuser \
  --data \
'{
  "name": "hello",
  "type": "mgnl:page",
  "path": "/demo-project/hello",
  "properties": [
    {
      "name": "title",
      "type": "String",
      "multiple": false,
      "values": [
        "Hello REST"
      ]
    },
    {
      "name": "mgnl:template",
      "type": "String",
      "multiple": false,
      "values": [
        "standard-templating-kit:pages/stkSection"
      ]
    }
   ]
}'

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.

Updating

Update content by issuing a POST request to the nodes or properties endpoint.

curl: PUT a new page

curl http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/demo-project/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"
      ]
    }
  ]
}'

Publishing

Publish (activate) content by issuing a POST request to the commands endpoint.

Publishing a page

curl http://localhost:8080/magnoliaAuthor/.rest/commands/v1/default/activate \
  -H "Content-Type: application/json" \
  -X POST --user superuser:superuser \
  --data \
'{
  "repository": "website",
  "path": "/demo-project/hello",
  "recursive": "false"
}'

Deleting

Delete content by issuing a POST request to the commands endpoint. Magnolia provides delete commands that unpublish the content first and then delete it.

Deleting a page with a command

curl http://localhost:8080/magnoliaAuthor/.rest/commands/v1/default/delete \
  -H "Content-Type: application/json" \
  -X POST --user superuser:superuser \
  --data \
'{
  "repository": "website",
  "path": "/demo-project/hello",
  "recursive": "false"
}'

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.

Deleting a page

curl http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/demo-project/hello \
  -H "Content-Type: application/json" \
  -X DELETE --user superuser:superuser

Swagger API explorer

The Swagger API explorer is the easiest way to learn the API. Swagger is a tool that shows what parameters and options the API accepts and how it responds to your requests. Swagger also acts as live documentation that is always up-to-date with the Magnolia instance it runs on. The tool understands both XML and JSON. You can find it in Dev > REST Tools when the REST Tools module is installed.

Once you learn the basics with Swagger, try making requests with cURL.

Authenticating

The REST API requires authentication. An anonymous user cannot interact with the API. Authenticate by passing a valid username and password with your request. The user must have a permission to issue requests on the endpoints.

Passing a username and password with a request

curl  --user superuser:superuser http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/demo-project

When you use the Swagger API explorer you are already logged into Magnolia. Any requests made in Swagger are executed with the permissions of currently logged-in account.

Security

Permissions to issue REST requests are controlled using Magnolia's standard role-based security mechanism .

rest role

The REST module installs a rest role which has the permission to issue requests to the nodes and properties endpoints by default.

Access control lists

Workspace	Permission	Scope	Path
Userroles	Read only	Selected	`/rest`

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*`

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.

Enabling commands

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:

Open the security app and grant the rest role a permission to the issue requests to the commands endpoint. Permission to the endpoint is denied by default. Add a new rule.

fake
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
catalogName	website
commandName	activate
markAsDeleted

Properties

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.

Versioning of services

The Web services are versioned. The version number is built into the service URI between the service path and the method name:

Version number in service URI

/.rest/nodes/v1/website/demo-project

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.

Correspondingly, Java endpoints are placed in *.v1, packages:

REST Services packages

info.magnolia.rest.service.node.v1
info.magnolia.rest.service.property.v1
info.magnolia.rest.service.command.v1

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

Exposing your own endpoints

To expose your own service endpoint:

Write a definition interface that extends the info.magnolia.rest.EndpointDefinition interface. See info.magnolia.rest.service.node.definition.NodeEndpointDefinition as an example.
Write an implementation class that implements or extends the info.magnolia.rest.EndpointDefinition interface. See info.magnolia.rest.service.node.definition.ConfiguredNodeEndpointDefinition as an example.
Configure the endpoint in Configuration > /modules/<your module>/rest-endpoints.
- Set the class property to your definition class.
- Set the implementationClass property to your implementation class.

Example:

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

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/demo-project

Page tree

REST API

REST API reference

nodes endpoint

properties endpoint

commands endpoint

Examples

Reading

Creating

Updating

Publishing

Deleting

Swagger API explorer

Authenticating

Security

rest role

Enabling commands

Versioning of services

Exposing your own endpoints