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. You need the Swagger API explorer tool that ships with the REST Tools submodule for the tutorial.

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 travel site. This is a very basic page that has a title but no content. It uses the standard page template. 

1. Open the Swagger API explorer.
2. Expand the nodes endpoint and add a PUT request which creates a new node.
3. Set the request parameters:
   
   • workspace: website.
   • path: travel.
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": "/travel/hello",
  "properties": [
    {
      "name": "title",
      "type": "String",
      "multiple": false,
      "values": [
        "Hello REST"
      ]
    },
    {
      "name": "mgnl:template",
      "type": "String",
      "multiple": false,
      "values": [
        "travel-demo:pages/standard"
      ]
    }
   ]
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<node>
  <name>hello2</name>
  <type>mgnl:page</type>
  <path>/travel/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>travel-demo:pages/standard</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 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 white list. It allows you to activate the page without workflow approval, which is quicker for the purposes of this tutorial.

   Node name	Value
   modules
   rest-services
   rest-endpoints
   commands
   enabledCommands
   activate-without-workflow
   access
   roles
   rest	rest
   catalogName	default
   commandName	activate

Properties:

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:  website  
   • 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": "/travel/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

Read on the parent page about how to create a page with cURL.

Publishing a page with cURL

Read on the parent page about how to publish a page with cURL.