Implemented in 5.2

First version.

The REST API can be used to execute commands and manipulate content stored in the JCR. They support both XML and JSON formats.

REST Web Service reference

XML format

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<node>
  <type>mgnl:page</type>
  <name>demo-project</name>
  <path>/demo-project</path>
  <identifier>1be12547-ad82-4c83-8396-213466ceb003</identifier>
 <properties>
    <property>
      <multiple>false</multiple>
      <name>title</name>
      <type>String</type>
      <values>
        <value>Home</value>
      </values>
    </property>
    <property>
      <multiple>false</multiple>
      <name>logoImg</name>
      <type>String</type>
      <values>
        <value>jcr:a1918662-8cbe-4346-ac5a-1b24a9950e2b</value>
      </values>
    </property>
  </properties>
  <children>
    <child>
      <children/>
      <identifier>2020f885-a96a-4899-8f74-cccc9ebcdb94</identifier>
      <name>footer</name>
      <path>/demo-project/footer</path>
      <properties>
        <property>
          <multiple>false</multiple>
          <name>copyright</name>
          <type>String</type>
          <values>
            <value>2010-2012 Magnolia International Ltd.</value>
          </values>
        </property>
      </properties>
      <type>mgnl:area</type>
    </child>
</node>

JSON format

{
    "name": "demo-project",
    "type": "mgnl:page",
    "path": "/demo-project",
    "identifier": "1be12547-ad82-4c83-8396-213466ceb003",
    "properties": [
        {
            "name": "title",
            "type": "String",
            "multiple": false,
            "values": ["Home"]
        },
        {
            "name": "logoImg",
            "type": "String",
            "multiple": false,
            "values": ["jcr:a1918662-8cbe-4346-ac5a-1b24a9950e2b"]
        }
    ],
    "children": [
        {
            "name": "footer",
            "type": "mgnl:area",
            "path": "/demo-project/footer",
            "identifier": "2020f885-a96a-4899-8f74-cccc9ebcdb94",
            "properties": [
                {
                    "name": "copyright",
                    "type": "String",
                    "multiple": false,
                    "values": ["2010-2012 Magnolia International Ltd. "]
                }
            ],
            "children": []
        }
    ]
}

API Description

CRUD (create, read, update & delete) content via a provided web service

Read

Example: get content of demo-project/about/history via web service: http://localhost:8090/magnolia-bundled-webapp/.rest/repositories/v1/website/demo-project/about/history?depth=1

response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<repositoryNode>
  <children>
    <child>
      <children/>
      <name>extras</name>
      <path>/demo-project/about/history/extras</path>
      <properties/>
      <type>mgnl:area</type>
      <uuid>d905396f-ac0f-4ea9-b8f2-bd0a9a6533a8</uuid>
    </child>
    <child>
      <children/>
      <name>promos</name>
      <path>/demo-project/about/history/promos</path>
      <properties/>
      <type>mgnl:area</type>
      <uuid>de17e68c-e74d-49ae-88a0-d7c0e29e17a7</uuid>
    </child>
...

Here's how this webservice is configured:

Magnolia commands can be exposed as webservices

( MGNLREST-6 - Getting issue details... STATUS )

You can adapt your instances to expose any command as a REST web service - no coding is needed. You just have to add the corresponding configuration:

Custom webservices can be exposed

( MGNLREST-14 - Getting issue details... STATUS )

You can also adapt your instances to expose any custom web service - again simply by adding the proper configuration.

Available web services are self documented and easily testable

( MGNLREST-1 - Getting issue details... STATUS )

Versioning of services

We decided to go for versioning within the URI

version numbers are v1, v2, v…
version number are placed between service path and method name
java endpoints are placed in *.v1, *.v2, … packages
java endpoints only contain the "sugar" required to expose web services - the logic that might be identical for different versions goes into service implementations
- e.g. CommandEndpoint delegates to the CommandManager (it's service)

Page tree

REST webservices