Page tree
Skip to end of metadata
Go to start of metadata

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.


Authenticating

By default, the REST API requires authentication. Authenticate by passing a valid username and password with your request.

Example: Passing a username and password with a curl 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.

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.

Web access

PermissionPath
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 toNamePath
CommandsDelete/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 (optional)

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.

(warning) 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:

  1. 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.
  2. Whitelist any commands you want to expose to REST. The white list is managed in /modules/rest-services/rest-endpoints/commands/enabledCommands.
Node nameValue

 modules


 rest-services


 rest-endpoints


 commands


 enabledCommands


 activate


 access


 roles


 rest

rest

 catalogName

website

 commandName

activate

 markAsDeleted


Properties:

enabledCommands

required

Enabled commands node.

<command>

required

Arbitrary name for the command. Use any name you like.

access

required

Access node.

roles

required

Roles node.

<role>

required

Role name. Grants the role permission to execute the command . Add the default rest role. The property name is arbitrary but the value must be a valid role name.

catalogName

required

Catalog where the command resides.

commandName

required

Command definition name.

REST API reference

The REST API has three endpoints: nodesproperties and commands. You can read, create, update and delete content by issuing requests to the endpoints.

nodes endpoint

GET
 /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

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

Creates a node and adds passed properties. Example: Creating content

(warning) 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

POST
 /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

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

Deletes a node.

Parameter

Description

Parameter type

Data type

workspace

Workspace

path

string

path


path

string

properties endpoint

GET
 /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 travel site

http://localhost:8080/magnoliaAuthor/.rest/properties/v1/website/travel/siteTitle
PUT
 /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

POST
 /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

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

Deletes a property.

Parameter

Description

Parameter type

Data type

workspace

Workspace

path

string

path


path

string

commands endpoint

POST
 /commands/v2/{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

POST
 /commands/v2/{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

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

For a JSON request, provide an HTTP request header field. You can do this using JavaScript or with cURL.

Read page /travel/about
<!-- 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>

Creating pages

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

Create a new page /travel/hello
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.

Creating assets

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:

Create a new asset /logo
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:

Create jcr:content node in asset: /logo
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 (\). 

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/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"
      ]
    }
  ]
}'

Publishing

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

Publishing a page
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"
}'

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

Deleting a page
curl http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/travel/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. Swagger API Explorer supports both XML and JSON in the request body but it returns only JSON. You can find the tool in Dev > REST Tools when the REST Tools module is installed.

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

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/travel

Versioning provides backwards compatibility. When Magnolia upgrades the REST API to v2, v1 will still exist. Calls that you wrote against v1 continue to work against v1. The version numbering scheme goes v1, v2, v3 and so on.

Correspondingly, Java endpoints are placed in versioned packages:

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

Version history

EndpointVersionWhat changedMagnolia version
nodesv1

First release

5.2
propertiesv1

First release

5.2
commandsv1

First release

5.2

v2

MGNLREST-62 - Getting issue details... STATUS

5.4.1


Exposing your own endpoints

To expose your own service endpoint:

  1. Write a definition interface that extends the EndpointDefinition interface. See NodeEndpointDefinition as an example.
  2. Write an implementation class that implements or extends the EndpointDefinition interface. See ConfiguredNodeEndpointDefinition as an example.
  3. Configure the endpoint in /modules/<your-module>/rest-endpoints.
    • Set the class property to your definition class.
    • Set the implementationClass property to your implementation class.

Example: REST endpoint configuration in /modules/rest-services/rest-endpoints/nodes.

Node nameValue

 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.

nodes

required

Name of the endpoint.

class

required

Definition class.

implementationClass

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
  • No labels

3 Comments

  1. Hello Guys,

    i am new here and need help.

    Can u give me an example how i can use the REST API for the import & export command? I have problems to set the input- and outputstreams via JSON.

    1. Hello Fatha

      I do not fully understand what exactly you intend to do. Please try to explain again.
      What do you want to import or export?

      By the way: If you ask at our forum (https://forum.magnolia-cms.com/forum.html) - the audience of readers who potentially can answer is bigger.

      1. My account is not working with your forum.

        I want to do something like this:

        curl http://localhost:8080/magnoliaAuthor/.rest/commands/v2/default/export \
          -H "Content-Type: application/json" \
          -X POST --user superuser:superuser \
          --data \
        '{
          "repository": "website",
          "path": "/test"
        }'

        But i get a NullpointerException, because the OutputStream for the export command is not defined. I thought that command will use the POST-Request Socket as the OutputStream.


        And I want to do something like this:

        curl http://localhost:8080/magnoliaAuthor/.rest/commands/v2/default/import \
          -H "Content-Type: application/json" \
          -X POST --user superuser:superuser \
          --data \
        '{
          "repository": "website",
          "path": "/",

          "xmlStream": "website.test.xml",

          "xmlFilename": "website.test.xml"

        }'

        website.test.xml is an Binary/XML File that should be transferred by the Post Request. But i dont know how the File can used by the REST API.