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

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)