Nodes API

This page describes the nodes API, which can be used to access and manipulate JCR nodes.

The Nodes API is best used as a content management API. For content delivery, we recommend using our Delivery API.

GET

Returns a node from the specified workspace and path.

Request URL

/.rest/nodes/v1/{workspace}/{path}

Parameters

Parameter Description Type Data Type

Parameter	Description	Type	Data Type
`workspace`	required The name of the workspace.	`path`	`String`
`path`	optional, default is `/` The absolute path to the node within the workspace.	`path`	`String`
`depth`	optional, default is `0` The depth of child nodes to be included. `0` is just the node itself. `1` is the node and its children etc.	`query`	`Integer`
`excludeNodeTypes`	optional A list of node types to be excluded.	`query`	`String`
`includeMetadata`	optional, default is `false` If set to `true`, the result will contain metadata properties.	`query`	`boolean`

workspace

required

The name of the workspace.

path

String

path

optional, default is /

The absolute path to the node within the workspace.

path

String

depth

optional, default is 0

The depth of child nodes to be included. 0 is just the node itself. 1 is the node and its children etc.

query

Integer

excludeNodeTypes

optional

A list of node types to be excluded.

query

String

includeMetadata

optional, default is false

If set to true, the result will contain metadata properties.

query

boolean

Example

Read the content of the /travel/about/company node from the website workspace including the metadata.

Get JSON Get XML

curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/travel/about/company?includeMetadata=true' \
-u superuser:superuser

curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/travel/about/company?includeMetadata=true' \
-u superuser:superuser -H "Accept: application/xml"

Get JSON Get XML

{
  "name": "company",
  "type": "mgnl:page",
  "path": "/travel/about/company",
  "identifier": "8fa4a73f-51c3-40ac-b698-715595216186",
  "properties": [
    {
      "name": "jcr:createdBy",
      "type": "String",
      "multiple": false,
      "values": [
        "admin"
      ]
    },
    {
      "name": "hideInNav",
      "type": "Boolean",
      "multiple": false,
      "values": [
        "false"
      ]
    },
    {
      "name": "mgnl:template",
      "type": "String",
      "multiple": false,
      "values": [
        "travel-demo:pages/standard"
      ]
    },
    {
      "name": "mgnl:lastActivatedBy",
      "type": "String",
      "multiple": false,
      "values": [
        "superuser"
      ]
    },
    {
      "name": "jcr:created",
      "type": "Date",
      "multiple": false,
      "values": [
        "2017-10-23T14:27:09.873+02:00"
      ]
    },
    {
      "name": "mgnl:lastActivated",
      "type": "Date",
      "multiple": false,
      "values": [
        "2017-10-23T14:27:13.852+02:00"
      ]
    },
    {
      "name": "mgnl:created",
      "type": "Date",
      "multiple": false,
      "values": [
        "2015-02-02T20:45:27.224+01:00"
      ]
    },
    {
      "name": "mgnl:createdBy",
      "type": "String",
      "multiple": false,
      "values": [
        "superuser"
      ]
    },
    {
      "name": "jcr:uuid",
      "type": "String",
      "multiple": false,
      "values": [
        "8fa4a73f-51c3-40ac-b698-715595216186"
      ]
    },
    {
      "name": "title",
      "type": "String",
      "multiple": false,
      "values": [
        "Our Company"
      ]
    },
    {
      "name": "title_de",
      "type": "String",
      "multiple": false,
      "values": [
        "Unser Unternehmen"
      ]
    },
    {
      "name": "mgnl:lastModified",
      "type": "Date",
      "multiple": false,
      "values": [
        "2015-10-27T13:48:35.936+01:00"
      ]
    },
    {
      "name": "mgnl:activationStatus",
      "type": "Boolean",
      "multiple": false,
      "values": [
        "true"
      ]
    },
    {
      "name": "jcr:primaryType",
      "type": "Name",
      "multiple": false,
      "values": [
        "mgnl:page"
      ]
    },
    {
      "name": "mgnl:lastModifiedBy",
      "type": "String",
      "multiple": false,
      "values": [
        "superuser"
      ]
    }
  ],
  "nodes": null
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<node>
  <identifier>8fa4a73f-51c3-40ac-b698-715595216186</identifier>
  <name>company</name>
  <path>/travel/about/company</path>
  <properties>
    <property>
      <multiple>false</multiple>
      <name>jcr:createdBy</name>
      <type>String</type>
      <values>
        <value>admin</value>
      </values>
    </property>
    <property>
      <multiple>false</multiple>
      <name>hideInNav</name>
      <type>Boolean</type>
      <values>
        <value>false</value>
      </values>
    </property>
    <property>
      <multiple>false</multiple>
      <name>mgnl:template</name>
      <type>String</type>
      <values>
        <value>travel-demo:pages/standard</value>
      </values>
    </property>
    <property>
      <multiple>false</multiple>
      <name>mgnl:lastActivatedBy</name>
      <type>String</type>
      <values>
        <value>superuser</value>
      </values>
    </property>
    <property>
      <multiple>false</multiple>
      <name>jcr:created</name>
      <type>Date</type>
      <values>
        <value>2017-10-23T14:27:09.873+02:00</value>
      </values>
    </property>
    <property>
      <multiple>false</multiple>
      <name>mgnl:lastActivated</name>
      <type>Date</type>
      <values>
        <value>2017-10-23T14:27:13.852+02:00</value>
      </values>
    </property>
    <property>
      <multiple>false</multiple>
      <name>mgnl:created</name>
      <type>Date</type>
      <values>
        <value>2015-02-02T20:45:27.224+01:00</value>
      </values>
    </property>
    <property>
      <multiple>false</multiple>
      <name>mgnl:createdBy</name>
      <type>String</type>
      <values>
        <value>superuser</value>
      </values>
    </property>
    <property>
      <multiple>false</multiple>
      <name>jcr:uuid</name>
      <type>String</type>
      <values>
        <value>8fa4a73f-51c3-40ac-b698-715595216186</value>
      </values>
    </property>
    <property>
      <multiple>false</multiple>
      <name>title</name>
      <type>String</type>
      <values>
        <value>Our Company</value>
      </values>
    </property>
    <property>
      <multiple>false</multiple>
      <name>title_de</name>
      <type>String</type>
      <values>
        <value>Unser Unternehmen</value>
      </values>
    </property>
    <property>
      <multiple>false</multiple>
      <name>mgnl:lastModified</name>
      <type>Date</type>
      <values>
        <value>2015-10-27T13:48:35.936+01:00</value>
      </values>
    </property>
    <property>
      <multiple>false</multiple>
      <name>mgnl:activationStatus</name>
      <type>Boolean</type>
      <values>
        <value>true</value>
      </values>
    </property>
    <property>
      <multiple>false</multiple>
      <name>jcr:primaryType</name>
      <type>Name</type>
      <values>
        <value>mgnl:page</value>
      </values>
    </property>
    <property>
      <multiple>false</multiple>
      <name>mgnl:lastModifiedBy</name>
      <type>String</type>
      <values>
        <value>superuser</value>
      </values>
    </property>
  </properties>
  <type>mgnl:page</type>
</node>

PUT

Creates a new node and adds the properties passed in the request.

You can add only one node per request. You cannot PUT nested nodes.

Request URL

/.rest/nodes/v1/{workspace}/{path}

Parameters

Parameter Description Type Data Type

Parameter	Description	Type	Data Type
`workspace`	required The name of the workspace to add a node to.	`path`	`String`
`path`	optional, default is `/` The absolute parent path of the new node.	`path`	`String`
`body`	required Request body format: JSON (default) or XML.	`body`	`String`

workspace

required

The name of the workspace to add a node to.

path

String

path

optional, default is /

The absolute parent path of the new node.

path

String

body

required

Request body format: JSON (default) or XML.

body

String

Example 1: Create a new page

Create a new page called /travel/hello (add a new node to the website workspace).

Put JSON Put XML

curl http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/travel \
-H "Content-Type: application/json" \
-X PUT -i \
--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 http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/travel \
-H "Content-Type: application/xml" \
-X PUT -i \
--user superuser:superuser \
--data \
'<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<node>
  <name>hello</name>
  <path>/travel/hello</path>
  <properties>
    <property>
      <multiple>false</multiple>
      <name>mgnl:template</name>
      <type>String</type>
      <values>
        <value>travel-demo:pages/standard</value>
      </values>
    </property>
    <property>
      <multiple>false</multiple>
      <name>title</name>
      <type>String</type>
      <values>
        <value>Hello REST</value>
      </values>
    </property>
  </properties>
  <type>mgnl:page</type>
</node>'

Tip: Use the -i option with cURL to show the HTTP response headers.

Example 2: Create a component in an area

After creating the new hello page using the above PUT request, you can also create a textImage component in the main area of /travel/hello/.

curl http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/travel/hello/main \
-H "Content-Type: application/json" \
-X PUT -i \
--user superuser:superuser \
--data \
'{
    "name": "0",
    "type": "mgnl:component",
    "path": "/travel/hello/main/0",
    "properties": [
        {
            "name": "headline",
            "type": "String",
            "multiple": false,
            "values": [
                "Hello REST"
            ]
        },
        {
            "name": "mgnl:template",
            "type": "String",
            "multiple": false,
            "values": [
            "travel-demo:components/textImage"
            ]
        }
    ]
}'

POST

Updates a node by adding the properties passed in the request. The method is changing only the properties passed with the response body. Other existing properties and subnodes are not affected.

Request URL

/.rest/nodes/v1/{workspace}/{path}

Parameters

Parameter Description Type Data Type

Parameter	Description	Type	Data Type
`workspace`	required The name of the workspace.	`path`	`String`
`path`	optional, default is `/` The path of the node to be updated.	`path`	`String`
`body`	required Request body format: JSON or XML.	`body`	`String`

workspace

required

The name of the workspace.

path

String

path

optional, default is /

The path of the node to be updated.

path

String

body

required

Request body format: JSON or XML.

body

String

Example

Update the title and hideInNav properties of the /travel/hello page.

Post JSON

curl http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/travel/hello \
-H "Content-Type: application/json" \
-X POST -i \
--user superuser:superuser \
--data \
'{
  "properties": [
    {
      "name": "title",
      "type": "String",
      "values": [
        "Hello REST updated"
      ]
    },
    {
      "name": "hideInNav",
      "type": "Boolean",
      "values": [
        true
      ]
    }
  ]
}'

curl http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/travel/hello \
-H "Content-Type: application/xml" \
-X POST -i \
--user superuser:superuser \
--data \
'<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<node>
  <properties>
    <property>
      <multiple>false</multiple>
      <name>title</name>
      <type>String</type>
      <values>
        <value>Hello REST - updated with XML :-P</value>
      </values>
    </property>
    <property>
      <multiple>false</multiple>
      <name>hideInNav</name>
      <type>Boolean</type>
      <values>
        <value>true</value>
      </values>
    </property>
  </properties>
</node>'

DELETE

Deletes a node.

Request URL

/.rest/nodes/v1/{workspace}/{path}

Parameters

Parameter Description Type Data Type

workspace

required

The name of the workspace.

path

String

path

optional, default is /

The path of the node which you want to delete.

Always provide a path. If default / is used, this will delete all content of the given workspace.

path

String

Example

Delete the /destinations/polar node in the category workspace:

curl -X DELETE 'http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/category/destinations/polar' \
-u superuser:superuser -i

The DELETE method is shown here for the sake of completeness only. If the content has already been published, applying this method is not a good idea. In most of your cases you had better apply the chained command delete with the commands endpoint instead of directy deleting the nodes via the DELETE method.