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

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. Swagger API Explorer supports both XML and JSON in the request body but it returns only JSON. You can find the tool 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 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!
Request body in JSON
{
  "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"
      ]
    }
   ]
}
 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>/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.

(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 issue requests to the commands endpoint.  Permission to the endpoint is denied by default. Add a new rule.
     
  1. skip
  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 nameValue

     modules


     rest-services


     rest-endpoints


     commands


     enabledCommands


     activate-without-workflow


     access


     roles


     rest

    rest

     catalogName

    default

     commandName

    activate

Properties:

enabledCommands

required

Enabled commands node.

<command>

required

Arbitrary name for the command. Use any name you like such as activate-without-workflow.

access

required

Access node.

roles

required

Roles node.

<role>

required

Role name. Grants the role permission to execute the command . Add the default rest role. The property name is arbitrary but the value must be a valid role name.

catalogName

required

Catalog where the command resides. Set the value to default. This is where the activate command that doesn't require approval is defined.

commandName

required

Command definition name. 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 website  
    • 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": "/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.