My first REST request

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

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!

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

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

 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.

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!

{
  "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

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

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