Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.

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

In this tutorial you learn to use Magnolia's REST API. We create and publish a page by issuing two requests to the API. Make sure the REST modules are installed. For this tutorial you need the Swagger API explorer tool that ships with the REST Tools submodule.

Overview

You will be making two requests to the REST API:

  1. PUT request to the nodes endpoint creates a page. In the request body you send a JSON representation of the new page.
  2. POST request to the commands endpoint publishes the page. In the request body you send a JSON reference to the page. 

 

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.

Creating a page

Let's create a new page under the demo-project site. This is a very basic page that has a title but no content. It uses the stkSection page template. 

  1. Open the Swagger API explorer in Dev > REST Tools.
  2. Expand the nodes endpoint and add a PUT request which creates a new node.
  3. Set the request parameters:
    • workspace: website  
    • path: demo-project
  4. Set the request body to a JSON or XML representation of a new page.
  5. Click Try it out!
Request body in JSON
{
  "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"
      ]
    }
   ]
}
 You can also send the body in XML. Click here to expand...
Request body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<node>
  <name>hello2</name>
  <type>mgnl:page</type>
  <path>/demo-project/hello2</path>
 <properties>
    <property>
      <name>title</name>
      <type>String</type>
      <multiple>false</multiple>
      <values>
        <value>Hello REST</value>
      </values>
    </property>
    <property>
      <name>mgnl:template</name>
      <type>String</type>
      <multiple>false</multiple>
      <values>
        <value>standard-templating-kit:pages/stkArticle</value>
      </values>
    </property>
  </properties>
</node>

Swagger will respond with "200" (OK) to a successful request.

 

Open the Pages app to verify that the page was created on the author instance.

Enabling the activation command

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.

  1. fake
  2. Whitelist any commands you want to expose to REST. The white list is managed in /modules/rest-services/rest-endpoints/commands/enabledCommands. Add an activate command in the default catalog to the whitelist. It allows you to activate the page without workflow approval, which is quicker for the purposes of this tutorial.
Node nameValue

 modules

 

 rest-services

 

 commands

 

 enabledCommands

 

 activate-without-workflow

 

 access

 

 roles

 

 rest

rest

 catalogName

default

 commandName

activate

Properties

  • enabledCommands 
    • <command> : Arbitrary name for the command. Use any name you like such as activate-without-workflow.
      • 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. Set the value to default. This is where the activate command that doesn't require approval is defined.
      • commandName Command definition. Set the value to activate

Publishing the page

The status of the new page on the author instance is red (=unpublished).  

When you view the website on the public instance you can see that the  hello  page is not yet there.

To publish the page:

  1. In Swagger API explorer, expand the  commands  endpoint.
  2. Add a POST request that allows you to specify a catalog.
  3. Set the request parameters:
    • catalogName default  
    • commandName activate
  4. Set the request body to a JSON representation of a reference to the hello page.
  5. Click Try it out!
Request body in JSON
{
  "repository": "website",
  "path": "/demo-project/hello",
  "recursive": "false"
}

Swagger responds with "200" (OK) to a successful request.

Open the Pages app to verify that the page was activated. The activation status is now green.

Visit the website on the public instance. The page is now visible in the navigation. 


Issuing requests with cURL

Do the same exercise using cURL. cURL is a command-line tool that you can use to make REST requests from outside Magnolia. When you request from outside you need to include additional parameters such as username, password and headers. While the Swagger explorer fills in such parameters automatically, you need to add them manually when using cURL.

The examples below are formatted as batch files for ease of reading. You can also use cURL directly from the command line. In that case, remove the backslashes and line breaks but escape the quotes in the JSON body with backslashes. 

Creating a page with cURL

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

Publishing a page with cURL

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

1 Comment

  1. How i can get APIs third parties in magnolia CMS, would you kindly give me example