REST API

Authenticating

By default, the REST API requires authentication. Authenticate by passing a valid username and password with your request.

curl --user superuser:superuser http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/travel

The username you pass must have a permission to issue requests to the endpoints. To grant the permission, assign the  rest role to the user.

Anonymous REST access is also possible but not configured by default. It is common to permit GET requests to some endpoints at certain paths, for example to use the REST API as a content provider for an AngularJS app that consumes content as JSON. To grant anonymous access, we recommend that you create a more limited rest-anonymous role that only grants GET permission to the relevant endpoint and path, then assign the new role to the anonymous user.

When you use the Swagger API explorer you are already logged into Magnolia. Any requests made in Swagger are executed with the permissions of the currently logged-in account.

Security

REST API reference

The REST API has three endpoints: nodes, properties and commands. You can read, create, update and delete content by issuing requests to the endpoints.

nodes endpoint

Returns a node from the specified workspace and path. Example: Reading content

Creates a node and adds passed properties. Example: Creating content

 You can add only one node per request. You can not put nested nodes.

Updates a node by adding passed properties. Example: Updating content

Deletes a node.

properties endpoint

Reads a property from a node.

Example: Get the siteTitle property of the travel site

http://localhost:8080/magnoliaAuthor/.rest/properties/v1/website/travel/siteTitle

Adds a property on a node.

Updates a property on a node.

Deletes a property.

commands endpoint

Executes a command in a catalog.

Executes a command in the default catalog.

Examples

 Learn to create and publish a page in a few steps with My first REST request.

Reading

Read content by issuing a GET request to the nodes or properties endpoint.

<!-- Request JSON -->
curl -H "Accept: application/json"  http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/travel/about  \
 -u superuser:superuser


<!-- Request XML -->
http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/travel/about

Response representation of /travel/about page:

{ 
   "name":"about",
   "type":"mgnl:page",
   "path":"/travel/about",
   "identifier":"808ebe4c-72b2-49f1-b9f7-e7db22bce02f",
   "properties":[  
      {  
         "name":"hideInNav",
         "type":"Boolean",
         "multiple":false,
         "value":[  
            "false"
         ]
      },
      {  
         "name":"title",
         "type":"String",
         "multiple":false,
         "value":[  
            "About"
         ]
      },
      {  
         "name":"title_de",
         "type":"String",
         "multiple":false,
         "value":[  
            "Über uns"
         ]
      }
   ],
   "node":null
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<node>
  <identifier>808ebe4c-72b2-49f1-b9f7-e7db22bce02f</identifier>
  <name>about</name>
  <path>/travel/about</path>
  <properties>
    <property>
      <multiple>false</multiple>
      <name>hideInNav</name>
      <type>Boolean</type>
      <values>
        <value>false</value>
      </values>
    </property>
    <property>
      <multiple>false</multiple>
      <name>title</name>
      <type>String</type>
      <values>
        <value>About</value>
      </values>
    </property>
    <property>
      <multiple>false</multiple>
      <name>title_de</name>
      <type>String</type>
      <values>
        <value>Über uns</value>
      </values>
    </property>
  </properties>
  <type>mgnl:page</type>
</node>

Creating pages

Create content by issuing a PUT request to the nodes or properties endpoint.

curl http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/travel \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -X PUT \
  --user superuser:superuser \
  --data \
'{
  "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"
      ]
    }
   ]
}'

Creating assets

Before uploading an asset via REST, make sure that the role assigned to the uploading user grants permissions to post data to the dam workspace.

Now create an asset by issuing PUT requests to the nodes endpoint. This requires two calls: the first creates the asset node and the second adds the binary data. 

 cURL command to create the asset node:

curl http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/dam \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -X PUT \
  --user superuser:superuser \
  --data \
'{
  "name": "logo",
  "type": "mgnl:asset",
  "path": "/logo",
  "properties": [
    {
      "name": "type",
      "type": "String",
      "multiple": false,
      "values": [
        "png"
      ]
    },
    {
      "name": "name",
      "type": "String",
      "multiple": false,
      "values": [
        "logo"
      ]
    },
    {
      "name": "type",
      "type": "String",
      "multiple": false,
      "values": [
        "png"
      ]
    }
  ]
}'

To upload the binary data, you must convert it into a String. When working with JSON, Base64 is a good format. (If you want to decode an image quickly, use an online tool such as Base64 Image).

cURL command to upload the binary node:

curl http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/dam/logo \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -X PUT \
  --user superuser:superuser \
  --data \
'{
  "name": "jcr:content",
  "type": "mgnl:resource",
  "path": "/logo/jcr:content",
  "properties": [
    {
      "name": "jcr:data",
      "type": "Binary",
      "multiple": false,
      "values": [ "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAFUlEQVQImWNs2Lz/PwMaYEIXoIIgAC8/AvuJXQkXAAAAAElFTkSuQmCC......" ]
    },
	{
      "name": "height",
      "type": "Long",
      "multiple": false,
      "values": [
        "5"
      ]
    },
    {
      "name": "width",
      "type": "Long",
      "multiple": false,
      "values": [
        "5"
      ]
    },
    {
      "name": "extension",
      "type": "String",
      "multiple": false,
      "values": [
        "png"
      ]
    },
    {
      "name": "fileName",
      "type": "String",
      "multiple": false,
      "values": [
        "logo.png"
      ]
    },
    {
      "name": "jcr:mimeType",
      "type": "String",
      "multiple": false,
      "values": [
        "image/png"
      ]
    }
  ]
}'

Uploading binary data manually with cURL is a cumbersome process, but you may want to use the REST API programmatically. Before doing so, test the endpoints with cURL or with swagger. When using cURL in the shell, be aware that every shell has an upper limit on the amount of characters per line. If you try to upload big images with cURL, you may have to split the Base64 decoded data into several lines with backslashs (\). 

Updating

Update content by issuing a POST request to the nodes or properties endpoint.

curl http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/travel/hello \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -X POST \
  -v \
  --user superuser:superuser \
--data \
'{
  "properties": [
    {
      "name": "title",
      "type": "String",
      "values": [
        "Hello REST updated"
      ]
    }
  ]
}'

Publishing

Publish (activate) content by issuing a POST request to the commands endpoint.

curl http://localhost:8080/magnoliaAuthor/.rest/commands/v2/website/activate \
  -H "Content-Type: application/json" \
  -X POST --user superuser:superuser \
  --data \
'{
  "repository": "website",
  "path": "/travel/hello",
  "recursive": "false"
}'

Deleting

Delete content by issuing a POST request to the commands endpoint. Magnolia provides delete commands that unpublish the content first and then delete it.

curl http://localhost:8080/magnoliaAuthor/.rest/commands/v2/default/delete \
  -H "Content-Type: application/json" \
  -X POST --user superuser:superuser \
  --data \
'{
  "repository": "website",
  "path": "/travel/hello",
  "recursive": "false"
}'

curl http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/travel/hello \
  -H "Content-Type: application/json" \
  -X DELETE --user superuser:superuser

Swagger API explorer

Once you learn the basics with Swagger, try making requests with cURL.

Versioning of services

The Web services are versioned. The version number is built into the service URI between the service path and the method name:

/.rest/nodes/v1/website/travel

Versioning provides backwards compatibility. When Magnolia upgrades the REST API to v2, v1 will still exist. Calls that you wrote against v1 continue to work against v1. The version numbering scheme goes v1, v2, v3 and so on.

Correspondingly, Java endpoints are placed in versioned packages:

info.magnolia.rest.service.node.v1
info.magnolia.rest.service.property.v1
info.magnolia.rest.service.command.v2

Java endpoints contain only code that is necessary to expose the Web services. Service logic goes into service implementations. For example, CommandEndpoint delegates to CommandsManager (its service).

Version history

Exposing your own endpoints

To expose your own service endpoint:

1. Write a definition interface that extends the
   $webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources") EndpointDefinition
    interface. See
   $webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources") NodeEndpointDefinition
   as an example.
2. Write an implementation class that implements or extends the 
   $webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources") EndpointDefinition
   interface. See 
   $webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources") ConfiguredNodeEndpointDefinition
   as an example.
3. Configure the endpoint in /modules/<your-module>/rest-endpoints.
   • Set the class property to your definition class.
   • Set the implementationClass property to your implementation class.

Example: REST endpoint configuration in /modules/rest-services/rest-endpoints/nodes.

Properties

Your endpoint is available at:

http://<domain>[:<port>]/<contextPath>/.rest/<endpoint>/<version>/{node}/{edge}

Here is a request URL to the nodes API. The endpoint is nodes and the edge is the workspace/path.  

http://localhost:8080/magnoliaAuthor/.rest/nodes/v1/website/travel