This documentation is still in progress. We are working hard to update all our screenshots to the new Magnolia 6 style. Please bear with us.

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

This page describes the delivery endpoint version 2 for obtaining JCR data as JSON.

This REST resource is highly customizable. You can define multiple endpoint configurations to serve different needs. Each configured endpoint is accessed through a distinct endpointPath and provides three methods. The methods, called with HTTP GET, allow you read a node (and its subnodes) by a given path, get children of a node and query nodes.

Methods

Please note that sending a request to a URI that ends with just the endpointPath invokes the Query nodes method. Attaching or not attaching the slash to the endpointPath has no effect in this:

GET <magnolia-base-path>/.rest/endpointPath/

GET <magnolia-base-path>/.rest/endpointPath


Read node

This method returns one node by a given path, including its properties and child nodes down to a certain depth. Child nodes are returned in the natural order.

Request URL

GET <magnolia-base-path>/.rest/endpointPath/{path}

Parameters

Parameter

Description

Data type

path

required

The path relative to the rootPath defined in the configuration.

String

Example

Get all component nodes of the main area of the /travel/about page.

curl 'http://localhost:8080/magnoliaAuthor/.rest/ep/travel/about/main' \
-u superuser:superuser
 Click to see the resulting JSON
{
  "@name": "main",
  "@path": "/travel/about/main",
  "@id": "f3b2681f-e747-4ff6-bcbb-2a9a9f01553e",
  "@nodeType": "mgnl:area",
  "00": {
    "@name": "00",
    "@path": "/travel/about/main/00",
    "@id": "01db6fc1-78af-4284-adf0-8c997309df6a",
    "@nodeType": "mgnl:component",
    "text": "<p>We are a full service, independent travel agency.</p>\n<p>We offer unique tours from every continent on the planet. Get inspired and book your tour with us for an experience you&rsquo;ll always remember.</p> ",
    "imagePosition": "below",
    "headlineLevel": "small",
    "headline": "About Magnolia Travels",
    "@nodes": []
  },
  "04": {
    "@name": "04",
    "@path": "/travel/about/main/04",
    "@id": "834ef0b0-1519-4834-b1f5-4166ae004ac0",
    "@nodeType": "mgnl:component",
    "layout": "8x4",
    "@nodes": []
  },
  "@nodes": [
    "00",
    "04"
  ]
}

This result is returned for the following configuration:

class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
workspace: website
depth: 2
nodeTypes:
 - mgnl:area
childNodeTypes:
 - mgnl:component
includeSystemProperties: false

Get children

((warning) Magnolia 5.6.6+) This method is a special variant of the read node method. It uses the @nodes handle to retrieve child nodes of a path in a configured endpoint. To use the handle, append it to the path of a URI:

Request URL

GET <magnolia-base-path>/.rest/endpointPath/{path}@nodes

(info) The items in the response are returned in their natural (unsorted) order, see also the  orderBy request parameter.

Examples

    • Get child nodes in the root of the ep endpoint:

      curl "https://localhost:8080/magnoliaAuthor/.rest/ep/@nodes" -u superuser:superuser

       Click to see the resulting JSON

      [
          {
              "@name": "travel",
              "@path": "/travel",
              "@id": "b06b82a2-74b0-4994-8015-028c4fd60716",
              "@nodeType": "mgnl:page",
              "hideInNav": "false",
              "description": "Magnolia Travels is a demonstration project for Magnolia CMS. Browse the site to get an overview of Magnolia CMS features, and learn how to edit the content online. Or download the project and dig into the sources to learn the key templating features of Magnolia CMS.",
              "searchResultPage": "6df1ebd8-fc9d-4db3-8539-02829c56b9f2",
              "title": "Travel Home",
              "keywords": "Magnolia CMS, Open Source CMS, Content management, Demonstration project, Demo project, Demo, Online demo, Website builder",
              "@nodes": [
              ]
          },
          {
              "@name": "sportstation",
              "@path": "/sportstation",
              "@id": "5f26a93e-9d21-4231-9e60-c8edbb0d339d",
              "@nodeType": "mgnl:page",
              "hideInNav": "false",
              "description": "Magnolia Travels is a demonstration project for Magnolia CMS. Browse the site to get an overview of Magnolia CMS features, and learn how to edit the content online. Or download the project and dig into the sources to learn the key templating features of Magnolia CMS.",
              "title": "Sportstation",
              "keywords": "Magnolia CMS, Open Source CMS, Content management, Demonstration project, Demo project, Demo, Online demo, Website builder",
              "@nodes": [
              ]
          }
      ]
      
      
      This result is returned for the endpoint called ep with the following configuration:

      class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
      workspace: website
      includeSystemProperties: false
      nodeTypes:
       - mgnl:page
    • Get child nodes in the root of the /travel page:

      curl "https://localhost:8080/magnoliaAuthor/.rest/ep/travel/@nodes" -u superuser:superuser

       Click to see the resulting JSON

      [
          {
              "@name": "tour-type",
              "@path": "/travel/tour-type",
              "@id": "05872876-073e-40a3-a3c5-0d0a18c1d43d",
              "@nodeType": "mgnl:page",
              "hideInNav": "false",
              "navigationTitle": "Tours",
              "title": "Tour Types",
              "@nodes": [
              ]
          },
          {
              "@name": "destination",
              "@path": "/travel/destination",
              "@id": "028a4a92-35df-45a3-b6ff-58381db74eb5",
              "@nodeType": "mgnl:page",
              "hideInNav": "false",
              "title": "Destinations",
              "@nodes": [
              ]
          },
          {
              "@name": "tour",
              "@path": "/travel/tour",
              "@id": "af4cd608-2dda-4535-a5e0-703ef92fd45a",
              "@nodeType": "mgnl:page",
              "hideInNav": "true",
              "title": "Tour detail",
              "@nodes": [
              ]
          },
          {
              "@name": "stories",
              "@path": "/travel/stories",
              "@id": "f8cbedd6-df91-4d7c-a952-2dc414d97704",
              "@nodeType": "mgnl:page",
              "title": "Stories",
              "@nodes": [
              ]
          },
          {
              "@name": "about",
              "@path": "/travel/about",
              "@id": "808ebe4c-72b2-49f1-b9f7-e7db22bce02f",
              "@nodeType": "mgnl:page",
              "hideInNav": "false",
              "title": "About",
              "@nodes": [
              ]
          },
          {
              "@name": "contact",
              "@path": "/travel/contact",
              "@id": "53b073cc-ea3a-4e44-bdea-8c8a790b55c5",
              "@nodeType": "mgnl:page",
              "hideInNav": "false",
              "title": "Contact",
              "@nodes": [
              ]
          },
          {
              "@name": "meta",
              "@path": "/travel/meta",
              "@id": "7ebd74f1-c6f7-4307-9953-afd549118a56",
              "@nodeType": "mgnl:page",
              "hideInNav": "true",
              "title": "Container for meta pages",
              "@nodes": [
              ]
          },
          {
              "@name": "book-tour",
              "@path": "/travel/book-tour",
              "@id": "60e1aa3e-23d6-4200-ad28-20c3b969ab89",
              "@nodeType": "mgnl:page",
              "hideInNav": "true",
              "title": "Book your tour",
              "@nodes": [
              ]
          },
          {
              "@name": "members",
              "@path": "/travel/members",
              "@id": "39257043-9524-49a8-bcf2-934ac797eddf",
              "@nodeType": "mgnl:page",
              "hideInNav": "false",
              "description": "Exclusive content, tips and special discounts for registered members.",
              "title": "Members",
              "@nodes": [
              ]
          },
          {
              "@name": "tour-finder",
              "@path": "/travel/tour-finder",
              "@id": "d25e69d9-27d0-4477-824c-7cc0714c97ce",
              "@nodeType": "mgnl:page",
              "hideInNav": "true",
              "title": "Tour Finder",
              "@nodes": [
              ]
          },
          {
              "@name": "tour-tag",
              "@path": "/travel/tour-tag",
              "@id": "a045a2d0-7b1c-466c-88bc-28352749959c",
              "@nodeType": "mgnl:page",
              "hideInNav": "true",
              "title": "Tagged tours",
              "@nodes": [
              ]
          }
      ]
      This result is returned for the endpoint called ep with the following configuration:

      class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
      workspace: website
      includeSystemProperties: false
      nodeTypes:
       - mgnl:page

Query nodes

Returns a list of nodes matching a query composed of the query parameters provided. You can also apply filters to the query.

Request URL

GET <magnolia-base-path>/.rest/endpointPath?param1=value1&param2=value2&... 

Use any of the optional query parameters or none.

Parameters

Parameter

Description

Parameter type

Data type

q

optional

A search phrase (full-text search).

query

String

orderBy

optional

The properties by which to order the nodes. The result may be returned either in the ascending ( asc ) order or in the descending ( desc ) order. The ascending order is applied if the direction is not set.

Example: mgnl:lastModified desc,title asc

Note that special characters such as a space (   ) must be encoded when sent in an HTTP request. When using tools to generate a REST request, this may happen automatically. With simple cURL you must encode it manually or with an additional tool.

Example: orderBy=title%20desc

(info) Please note that until Magnolia 5.6.5 the results provided by the endpoint were sorted alphabetically on node names (same as with the ORDER BY LOWER(NAME(t)) statement in the JCR-SQL2 query) even though no orderBy parameter was set in the request URL.

Since Magnolia 5.6.5 the results are returned unsorted if no orderBy parameter is set. This however does not mean "in natural order" since many other aspects may be involved, such as the setting of the respectDocumentOrder property or index consistency. For more information, see Apache Jackrabbit Search and Rebuilding the Index.

query

String

offset

optional, default is 0

The start position in a result list (for pagination).

queryInteger

limit

optional, default is as set in configuration

The number of nodes displayed in a page query. Use together with offset for pagination.

query

Integer

<filter>

optional

There are multiple filter options to filter for a property of the node, for node names, for nodes which must be ancestors of a given path, and so on. You can combine filters with an AND operator. See filter options.



Examples follow after the Filters section.

Filters

queryNodes provides a filtering mechanism. Filters are added as request parameters. Filter values must be properly URL-encoded. You can use multiple filters within the same request.

Filter format

The filter parameter has the following format: property[operator]=value

Example filter used in a URL:

http://localhost:8080/magnoliaAuthor/.rest/my-endpoint?description[like]=%25demonstration%25
Supported filter operators

OperatorMeaning
eq=
ne<>
gt>
lt<
lte<=
gte>=
inIN
not-inNOT IN

like

Can be used with:

% (percentage, URL encoded as %25)

_ (underscore) 

LIKE

Can be used with:

  • Percentage - Wildcard character that can be used in the search pattern to mean zero or more additional characters.
  • Underscore - Wildcard character that can be used in the search pattern to stand for any single character.
null

NULL ((warning) Magnolia 5.6.6+)

The value can be either true or false. For example, sending mgnl:created[null]=false is equivalent to issuing mgnl:created IS NOT NULL in JCR query.

The operator can be used with any property.

Filter types

Property filter

Filter for a node property. The property value must be an exact match.

author=Magnolia%20Travels


@name property filter

Filter by a node name.

@name=travel


@jcr:uuid filter

Filter by the JCR node ID (uuid). The property value must be an exact match.

@jcr:uuid=<id>


@ancestor filter

Find nodes for which the path provided is the ancestor. The path must be absolute in the given workspace of the given workspace prefix.

@ancestor=/travel/about/careers/marketing-associate
Usage notes
  • If no operator is provided, eq is used by default.

  • The value in the filter parameter is treated as String.

  • Use brackets to pass an operator, for example [eq][ne][lt], and so on.

  • For in and not-in, a range symbol ~ (the tilde) should be provided, for example:

    http://localhost:8080/magnoliaAuthor/.rest/my-endpoint?mgnl:created[in]=2015-12-01~2015-12-31
  • Ranges are inclusive: price[in]=100~200 is interpreted as price >= 100 AND price <= 200.
  • For filtering by date and time, only two ISO 8601-based formats are accepted. The patterns shown are in JAVA notation (java.text.SimpleDateFormat):
    • Date:  yyyy-MM-dd

      2018-01-01
    • Datetime:  yyyy-MM-dd'T'HH:mm:ss.SSSXXX

      2018-01-11T10:26:47.438+07:00
  • If a filter can take multiple possible values which must match, use | (OR):

    @name=travel|about

Examples

We assume you are familiar with cURL. Note that cURL requires URL encoding.

See tools to test REST requests for other possibilities.

    • Find webpages in the Travel Demo which were last modified before or on June 3, 2015: 

      curl 'http://localhost:8080/magnoliaAuthor/.rest/ep/?mgnl:lastModified[lte]=2015-06-12' --globoff \
      -u superuser:superuser
      (info) By using the option --globoff you can specify URLs that contain the letters {}[] without having them being interpreted by cURL itself.

       Click to see the endpoint configuration and the resulting JSON

      Endpoint: ep

      class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
      workspace: website
      rootPath: /
      nodeTypes:
       - mgnl:page

      Response

      {
        "results": [
          {
            "@name": "meta",
            "@path": "/travel/meta",
            "@id": "7ebd74f1-c6f7-4307-9953-afd549118a56",
            "@nodeType": "mgnl:page",
            "jcr:createdBy": "admin",
            "hideInNav": "true",
            "mgnl:template": "travel-demo:pages/standard",
            "mgnl:lastActivatedBy": "superuser",
            "jcr:created": "2018-03-16T14:43:26.638+01:00",
            "mgnl:lastActivated": "2018-03-16T14:43:39.506+01:00",
            "mgnl:created": "2015-02-02T20:58:23.939+01:00",
            "mgnl:createdBy": "superuser",
            "title": "Container for meta pages",
            "mgnl:lastModified": "2015-06-03T20:37:49.283+02:00",
            "mgnl:activationStatus": "true",
            "mgnl:lastModifiedBy": "superuser",
            "@nodes": []
          }
        ]
      }

    • Find webpages with the word "Customer" in the title.

      curl -g -G "http://localhost:8080/magnoliaAuthor/.rest/ep" --data-urlencode "title[like]=%Customer%" -u superuser:superuser
      Use --data-urlencode and -g -G to encode the request parameter values, if required.

       Click to see the endpoint configuration and the resulting JSON

      Endpoint: ep

      class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
      workspace: website
      rootPath: /
      nodeTypes:
       - mgnl:page
      includeSystemProperties: false

      Response

      {
        "results": [
          {
            "@name": "customer-experience-agent",
            "@path": "/travel/about/careers/customer-experience-agent",
            "@id": "1f8af166-258f-4351-a543-3d0fc8bb00c0",
            "@nodeType": "mgnl:page",
            "hideInNav": "false",
            "title": "Customer Experience Agent",
            "@nodes": []
          },
          {
            "@name": "customer-experience-supervisor",
            "@path": "/travel/about/careers/customer-experience-supervisor",
            "@id": "c8e6902a-499a-44d7-9de9-45fd93d60a6b",
            "@nodeType": "mgnl:page",
            "hideInNav": "false",
            "title": "Customer Experience Supervisor",
            "@nodes": []
          }
        ]
      }

      Due to the use of a wildcard character in the URL with the [like] filter the number of results can potentially be higher.

    • In the website workspace, find all nodes for which /travel/about/careers is the ancestor:

      curl 'http://localhost:8080/magnoliaAuthor/.rest/ep/?@ancestor=/travel/about/careers' \
      -u superuser:superuser
       Click to see the endpoint configuration and the resulting JSON

      Endpoint: ep

      class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
      workspace: website
      rootPath: /
      includeSystemProperties: false
      nodeTypes:
       - mgnl:page

      Response

      {
        "results": [
          {
            "@name": "customer-experience-agent",
            "@path": "/travel/about/careers/customer-experience-agent",
            "@id": "1f8af166-258f-4351-a543-3d0fc8bb00c0",
            "@nodeType": "mgnl:page",
            "hideInNav": "false",
            "title": "Customer Experience Agent",
            "@nodes": []
          },
          {
            "@name": "marketing-associate",
            "@path": "/travel/about/careers/marketing-associate",
            "@id": "f19c60f2-3049-4883-a170-4bf65e3abb91",
            "@nodeType": "mgnl:page",
            "hideInNav": "false",
            "title": "Marketing Associate",
            "@nodes": []
          },
          {
            "@name": "customer-experience-supervisor",
            "@path": "/travel/about/careers/customer-experience-supervisor",
            "@id": "c8e6902a-499a-44d7-9de9-45fd93d60a6b",
            "@nodeType": "mgnl:page",
            "hideInNav": "false",
            "title": "Customer Experience Supervisor",
            "@nodes": []
          }
        ]
      }

    • Find nodes in the tours workspace that contain the keyword "beach". Return the results in descending order based on the location property and restrict the number of results to three:

      curl 'http://localhost:8080/magnoliaAuthor/.rest/ep/?q=beach&orderBy=location%20desc&limit=3' \
      -u superuser:superuser

       Click to see the endpoint configuration and the resulting JSON

      Endpoint: ep

      class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
      workspace: tours
      includeSystemProperties: false

      Response

      {
        "results": [
          {
            "@name": "Beach-Paradise-in-Brazil",
            "@path": "/magnolia-travels/Beach-Paradise-in-Brazil",
            "@id": "545d5815-a3dd-4b68-a539-c38eb1bba29b",
            "@nodeType": "mgnl:content",
            "isFeatured": "true",
            "name": "Beach Paradise in Brazil",
            "description": "An Amazonian beach holiday",
            "location": "São Luís, Brasil",
            "tourTypes": [
              "082c340c-b062-4b15-86b8-96dd9deff680"
            ],
            "author": "Magnolia Travels",
            "body": "<p>When you hear &ldquo;Amazon&rdquo;, you probably think of a deep jungle. Well, this remarkably well hidden beach paradise is right in the middle of it. &nbsp;Alter do Ch&atilde;o lies on Rio Tapaj&oacute;s, a tributary to the mighty Amazon, which is so wide here that you can&rsquo;t even see across to the far shore. &nbsp;There&rsquo;s plenty of nature to explore in the area on foot, but the inlet to the lake is also covered with cosy beach restaurants and bars, perfect for a post swim chill out. &nbsp;</p>\n<p>No fear of crocodiles here, but there are some sting rays to watch out for. &nbsp;You&rsquo;ll start your adventure on the two-day boat ride from Manaus (capital of the Amazon) to Santar&eacute;m, but be sure to bring your own hammock (and some rope) or just some extra coins for the bar!</p>\n<p>While you&rsquo;re here, you&rsquo;ll discover there&rsquo;s much more to do than hanging out at the glorious beaches. The town lies at the entrance to the Lago Verde lagoon, home to many Amazon animals, and the perfect place to do a canoe trip. We also include tours to the beautiful Floresta Nacional do Tapaj&oacute;s and Rio Arapiuns.</p> ",
            "destination": [
              "bed2e297-199c-4dc8-90cd-54ad3cb4221b"
            ],
            "duration": "14",
            "image": "jcr:950cc73c-1b12-4f2a-bba7-97ad9d171f5d",
            "@nodes": []
          },
          {
            "@name": "West-Coast---Highway-101",
            "@path": "/magnolia-travels/West-Coast---Highway-101",
            "@id": "730c8850-d638-4e91-b3fb-4041a0c59ffe",
            "@nodeType": "mgnl:content",
            "body": "<p>Imagine walking in the footsteps of the explorers, missionaries, and soldiers who made America what it is today. Discover the famous El Camino Real (The Royal Road) based on the old trail which linked the Spanish Missions, Pueblos and Presidios.</p>\n<p>We&#39;ll kick off in Seattle and head south into Oregon and finally to California where we&#39;ll hit the beaches on California Highway 1. The trip will be infused with history and fabulous scenery, but there&rsquo;ll be lots of time for fun, with some great beach activities at the end of the trip.</p> ",
            "name": "West Coast - Highway 101",
            "description": "Family travels in USA",
            "destination": [
              "ed3dcd18-78af-46df-a9e1-bc732479f2e7"
            ],
            "location": "Seattle, USA",
            "tourTypes": [
              "17da160b-da66-4e09-9e31-5fd040880f4a"
            ],
            "author": "Magnolia Travels",
            "duration": "7",
            "image": "jcr:d44f783c-91ca-4b48-9533-ea4e147e13e9",
            "@nodes": []
          },
          {
            "@name": "Dubai-and-Oman",
            "@path": "/magnolia-travels/Dubai-and-Oman",
            "@id": "5007ccb4-0332-4a20-aef7-bf8155ab9340",
            "@nodeType": "mgnl:content",
            "body": "<p>This unique trip will give you some real insights into life in the Arabian Peninsula, while also allowing you plenty of time to soak up the sun. You&rsquo;ll start your trip in ancient Oman, where life still goes on much the way it did centuries ago. You&rsquo;ll be able to visit Muscat&rsquo;s fascinating souk to haggle for some handmade silver and pots. Then you can take a stroll along the lively harbour and visit some of the city&rsquo;s winding lanes. Round out the day relaxing on a beach chair at the Grand Hyatt, overlooking the Beach of Oman.</p>\n<p>In Dubai, we&rsquo;ll visit some of the city&rsquo;s wonders, like Burj al Khalifa, the tallest building in the world, and Dubai Mall, the biggest shopping mall in the world, with its magnificent aquarium. But after all the sightseeing, there&rsquo;s nothing better than relaxing at the beach at the luxury Atlantis Hotel, located on the Palm Jumeirah, a man-made palm shaped island. Magnolia Travels will make sure this is a holiday you never forget!</p> ",
            "name": "Dubai and Oman",
            "description": "An unforgettable experience in the Arabian Gulf",
            "destination": [
              "79da73f7-900b-4c91-b58b-3b1355485519"
            ],
            "location": "Muscat, Oman",
            "tourTypes": [
              "e007e401-1bf8-4658-8293-b9c743784264"
            ],
            "duration": "7",
            "author": "Magnolia Travels",
            "image": "jcr:7eeb9a4f-72ef-43f4-a392-5c1916b31e3a",
            "@nodes": []
          }
        ]
      }

    • Find a tour with the word "Japan" in its description. Return only the variant in the German language:

      curl -g -G 'http://localhost:8080/magnoliaAuthor/.rest/ep?lang=de-DE' --data-urlencode "description[like]=%Japan%"  \
      -u superuser:superuser

      Note that we use --data-urlencode to encode one of the request parameters, whereas the one that does not require encoding is added to the URL directly.

       Click to see the endpoint configuration and the resulting JSON

      Endpoint: ep

      class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
      workspace: tours
      includeSystemProperties: false

      Response

      {
        "results": [
          {
            "@name": "Kyoto",
            "@path": "/magnolia-travels/Kyoto",
            "@id": "b475f27e-2929-427b-9517-815118a3b36e",
            "@nodeType": "mgnl:content",
            "body": "<p>Erleben Sie die Sch&ouml;nheit, die Kyoto durchdringt und umgibt. Kyoto ist ber&uuml;hmt f&uuml;r viele Dinge, darunter unz&auml;hlige <a href=\"http://www.japan-guide.com/e/e2058.html\" target=\"_blank\">Tempel</a>, <a href=\"http://www.japan-guide.com/e/e2059.html\" target=\"_blank\">Schreine</a> und andere faszinierende historische Bauwerke.</p>\n<p>Kommen Sie mit uns auf einen Besuch der Stadt der zehntausend Schreine. Wir besuchen To-ji, Ginkaku-ji, Kōzan-ji und ihre bemerkenswerten G&auml;rten, bevor wir einen Abstecher zu den Bergen in der Umgebung der Stadt machen. Sie werden es genie&szlig;en, einen Tag im gr&uuml;nen Miyama und einen Tag mit Wandern in Shizuhara zu verbringen. Sie werden nie wieder wie bisher &uuml;ber Japan denken.</p> ",
            "name": "Kyoto",
            "description": "Die natürliche Seite Japans",
            "destination": [
              "7ec72c48-c33f-418e-b2ff-44cfb4bbb1f2"
            ],
            "location": "Kyoto, Japan",
            "tourTypes": [
              "d2245867-ecaa-4b4e-8743-e0c939be68b7",
              "415025c6-e4b5-4506-9384-34f428a52104"
            ],
            "author": "Magnolia Travels",
            "duration": "7",
            "image": "jcr:44689d29-5966-4d41-8fd4-2dc7da783528",
            "@nodes": []
          }
        ]
      }


Filtering on specific languages

To get REST results for a specific language you may have to specify a language suffix in the search query. Let's consider an example based on the default installation of the Travel Demo bundle, where the content in the Tours app (stored in the tours workspace) is available both in English and in German and English is the default language for the site.

Searching for Erleben in the content of the body properties of the workspace by sending a query such as http://localhost:8080/magnoliaAuthor/.rest/ep/?body[like]=%Erleben% yields no results since Erleben is present only in the German content variant:

In the search query you need specify the language by appending - in this case - the _de suffix to the body property and re-send http://localhost:8080/magnoliaAuthor/.rest/ep/?body_de[like]=%Erleben% instead. Only this will return a result (click the link to expand to see the actual result):

 Click here to expand...
{
  "results": [{
    "@name": "Kyoto",
    "@path": "/magnolia-travels/Kyoto",
    "@id": "b475f27e-2929-427b-9517-815118a3b36e",
    "@nodeType": "mgnl:content",
    "name": "Kyoto",
    "description": "The natural side of Japan",
    "location": "Kyoto, Japan",
    "tourTypes": ["d2245867-ecaa-4b4e-8743-e0c939be68b7", "415025c6-e4b5-4506-9384-34f428a52104"],
    "author": "Magnolia Travels",
    "body": "<p>Experience the still beauty that permeates and surrounds Kyoto. Kyoto is famous for many things, including countless <a href=\"http://www.japan-guide.com/e/e2058.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>temples</u></a>, <a href=\"http://www.japan-guide.com/e/e2059.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>shrines</u></a> and other fascinating historical buildings.</p>\n<p>Join us on a visit to the City of Ten Thousand Shrines. We&#39;ll visit Tō-ji, Ginkaku-ji, Kōzan-ji and their remarkable gardens before venturing into the mountains that surround the city. You&rsquo;ll enjoy a day spent in green Miyama and a day hiking in Shizuhara. You&rsquo;ll never think about Japan in the same way again.</p> ",
    "destination": ["7ec72c48-c33f-418e-b2ff-44cfb4bbb1f2"],
    "duration": "7",
    "image": "jcr:44689d29-5966-4d41-8fd4-2dc7da783528",
    "@nodes": []
  }]
}

This result is returned for the endpoint called ep with the following configuration:

class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
workspace: tours
includeSystemProperties: false

(warning) Notice that in spite of searching within body_de the content in the output is in English. This is caused by sending the en value in the Content-Language header sent along with the query. To obtain a response with content in German, you would need to append &lang=de to the query.

If you try to find the English equivalent (Experience), you must not specify the _en suffix since English is the site's default language. Using this suffix in the query returns an empty result set:

{"results":[]}

There's no property body_en present in the tours workspace.

Alternatively, try searching with a more general search query such as http://localhost:8080/magnoliaAuthor/.rest/ep/?q=Erleben which will also return a response where Erleben appears in the JCR (endpoint configuration is same as the one above):

 Click here to expand...
{
  "results": [{
    "@name": "North-Sea-Islands",
    "@path": "/magnolia-travels/North-Sea-Islands",
    "@id": "a2a00b27-7e39-4230-8c79-3ffc5a678a15",
    "@nodeType": "mgnl:content",
    "name": "North Sea Islands",
    "description": "At the mercy of the sea",
    "location": "Hamburg, Germany",
    "tourTypes": ["e007e401-1bf8-4658-8293-b9c743784264", "d2245867-ecaa-4b4e-8743-e0c939be68b7"],
    "author": "Magnolia Travels",
    "body": "<p>Off Germany&rsquo;s coast in the North Sea lie the remote, romantic Halligen islands. Here, you&rsquo;ll experience a unique environment and way of life shaped by the tides. Houses here are built on meter high man-made hills called Warften to keep them above the sea-floods - known here as Land Unter. The islands are traced with tiny canals to drain the water after storms. But the locals, some 400 people, have also installed dams to let the silt settle out of the water. They must rely on this to slowly build up the height of the islands. It&rsquo;s like a slow-motion race against erosion and rising oceans. Speaking of slow - you&rsquo;ll have plenty of opportunity to enjoy the island pastimes like the local card game (also called Land Unter), flying kites, or just wandering the wind-buffeted pastures, lightly populated with happy sheep and contented cows.</p>\n<p>Our trip will include walks on the extensive salt coated mudflats of this <a href=\"http://www.germany.travel/en/towns-cities-culture/unesco-world-heritage/the-wadden-sea.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>World Heritage</u></a> nature reserve, where you&rsquo;ll be able to observe some rare birdlife. We&rsquo;ll discover many other fascinating critters, like ants that have adapted to build special nests that can withstand the periodic flooding. The broken remnants of houses and household goods to be found on the flats are a reminder of the elemental forces which shape the islands, and our tenuous relationship with them.</p> ",
    "destination": ["6cc50e28-fb0e-4e49-b3b6-728690a2e861"],
    "duration": "7",
    "image": "jcr:7f3cbb8f-a909-47da-b678-543ce6f244b9",
    "@nodes": []
  }, {
    "@name": "Lapland-for-Families",
    "@path": "/magnolia-travels/Lapland-for-Families",
    "@id": "705051cb-c0c3-43b2-b5fa-c571b5d5d2d4",
    "@nodeType": "mgnl:content",
    "isFeatured": "true",
    "name": "Lapland for Families",
    "description": "Your own Arctic Circle adventure",
    "location": "Kittilä, Finland",
    "tourTypes": ["415025c6-e4b5-4506-9384-34f428a52104", "17da160b-da66-4e09-9e31-5fd040880f4a"],
    "author": "Magnolia Travels",
    "body": "<p>Enjoy a family winter adventure in Lapland, Sweden where sledding, husky sledding and ice skating are all on the menu. We lend you toboggans for sledding, and there are gentle hills right outside your cabin. For something more adventurous, join our &lsquo;crazy slope&rsquo; days out. Children will love the chance to drive their own sled, and snowballs and snowmen are possible any time of the day. You&rsquo;ll also get the chance to experience the spectacular Northern Lights.</p>\n<p><br /> At Christmas time, children can also join visits to Santa and his famous grotto, going on a unique snowmobile journey to see where Santa manages all his toy operations.</p> ",
    "destination": ["ee483660-15cd-490d-b709-884b3f130286"],
    "duration": "7",
    "image": "jcr:71b9a58b-3c78-41bd-9fe4-17ce0f3b5dd4",
    "@nodes": []
  }, {
    "@name": "Kyoto",
    "@path": "/magnolia-travels/Kyoto",
    "@id": "b475f27e-2929-427b-9517-815118a3b36e",
    "@nodeType": "mgnl:content",
    "name": "Kyoto",
    "description": "The natural side of Japan",
    "location": "Kyoto, Japan",
    "tourTypes": ["d2245867-ecaa-4b4e-8743-e0c939be68b7", "415025c6-e4b5-4506-9384-34f428a52104"],
    "author": "Magnolia Travels",
    "body": "<p>Experience the still beauty that permeates and surrounds Kyoto. Kyoto is famous for many things, including countless <a href=\"http://www.japan-guide.com/e/e2058.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>temples</u></a>, <a href=\"http://www.japan-guide.com/e/e2059.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>shrines</u></a> and other fascinating historical buildings.</p>\n<p>Join us on a visit to the City of Ten Thousand Shrines. We&#39;ll visit Tō-ji, Ginkaku-ji, Kōzan-ji and their remarkable gardens before venturing into the mountains that surround the city. You&rsquo;ll enjoy a day spent in green Miyama and a day hiking in Shizuhara. You&rsquo;ll never think about Japan in the same way again.</p> ",
    "destination": ["7ec72c48-c33f-418e-b2ff-44cfb4bbb1f2"],
    "duration": "7",
    "image": "jcr:44689d29-5966-4d41-8fd4-2dc7da783528",
    "@nodes": []
  }, {
    "@name": "Jordan-s-Pearls",
    "@path": "/magnolia-travels/Jordan-s-Pearls",
    "@id": "3351f7b2-e67b-4dbd-a6c6-7394eaf86d36",
    "@nodeType": "mgnl:content",
    "isFeatured": "false",
    "name": "Jordan’s Pearls",
    "description": "Seeking the crossroads of civilisations ",
    "location": "Amman, Jordan",
    "tourTypes": ["e007e401-1bf8-4658-8293-b9c743784264"],
    "author": "Magnolia Travels",
    "body": "<p>This trip will give you a deep insight into the Middle East, allowing you to not only experience its rich and ancient heritage, but also to get a glimpse into daily life. The trip starts by flying into Amman, capital of Jordan. Shortly outside the city, we&rsquo;ll take you to visit the breath-taking UNESCO world heritage site of Petra, an ancient city carved into the red rock by Nabateans. It is one of the world&rsquo;s most important archaeological sites.</p>\n<p>From there, we&rsquo;ll go by road to Jerash, often called the &lsquo;Pompeii of the East&rsquo;. The ancient Roman ruins at Jerash are famous for their remarkable state of preservation.</p> ",
    "destination": ["79da73f7-900b-4c91-b58b-3b1355485519"],
    "duration": "7",
    "image": "jcr:2b51aaf3-dc5a-4012-89e5-d3b3dd6c08cb",
    "@nodes": []
  }]
}

Configuration

You can define multiple endpoints in this version of the delivery endpoint. The endpointPath property is used to access the different configured endpoints.

Example

restEndpoints/my-endpoint.yaml
class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
workspace: website
limit: 25
depth: 2
includeSystemProperties: false
nodeTypes:
  - mgnl:page
childNodeTypes:
  - mgnl:area
  - mgnl:component
#references
Node nameValue

 restEndpoints


 my-endpoint


 class

info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition

 workspace

website

 limit

25

 depth

2

 includeSystemProperties

false

 nodeTypes


 0

mgnl:page

 childNodeTypes


 0

mgnl:area

 1

mgnl:component

Properties

class

required

Must be info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition or a subclass.

endpointPath

optional

If the property is not set, the endpointPath is evaluated automatically.

If you set the property manually, it should not contain special characters to fit into a proper URL.

workspace

required

The name of the JCR workspace to deliver content from.

rootPath

optional, default is /

The root path of this endpoint.

The path information when requesting the endpoint is added to this path.

nodeTypes

optional , default is mgnl:content

A list of allowed node types for depth-0 nodes.

childNodeTypes

optional , default is mgnl:contentNode

A list of allowed node types for child nodes.

strict

optional , default is false

((warning) Magnolia 5.6.6+) Defines whether to include only the exact node type and ignore the sub types.

If true then it is applied to both the nodeTypes and childNodeTypes.

depth

optional, default is 0

The depth of child nodes to include in each returned item.

This does not restrict which nodes will be returned from a query. It just determines the number of child nodes in each returned item.

includeSystemProperties

optional, default is true

Specifies whether the result should show system properties.

limit

optional, default is 10

The number of nodes (of level 0) in the result. Used only in the queryNodes method.

The property can be overridden when calling queryNodes with a request parameter.

bypassWorkspaceAcls

optional, default is false

If set to true, JCR security is bypassed. Use this property with care and for development purposes only.

references

optional

The references property allows to define to resolve referenced nodes.

The endpointPath property

The endpointPath is used to access a configured delivery endpoint.

<magnolia-base-path>/.rest/endpointPath/{path}
<magnolia-base-path>/.rest/endpointPath?query-parameters

The value of the endpointPath can be set as a property in the configuration. If you do not set the property manually, the system evaluates it automatically.

If you do not set the property in the configuration: 

  • The value set by the system is the path of the configuration relative to the restEndpoints folder.
  • You can add  _v$number  to the YAML file name or JCR node name that defines the endpoint in order to add a version to the  endpointPath evaluated by the system .

Examples:

YAML file locationendpointPath
my-module/restEndpoints/my-endpoint.yamlmy-endpoint
my-module/restEndpoints/foobar/another-endpoint.yamlfoobar/another-endpoint
my-module/restEndpoints/foobar/another-endpoint_v3.yamlfoobar/another-endpoint/v3
JCR node path inconfiguration workspaceendpointPath
/modules/my-custom-module/restEndpoints/super-endpointsuper-endpoint
/modules/my-custom-module/restEndpoints/foobar/mega-endpointfoobar/mega-endpoint
/modules/my-custom-module/restEndpoints/foobar/mega-endpoint_v2foobar/mega-endpoint/v2

Location of the endpoint definitions

Magnolia REST endpoint definitions are true Magnolia Resources. You can create them in a light module, in a Magnolia Maven module or in the JCR configuration workspace.

In a light module

Add configurations to the folder restEndpoints or to subfolders.

my-light-module/
└── restEndpoints
    ├── foobar
    │   └── another-endpoint.yaml
    └── my-endpont.yaml

In a Magnolia Maven module

Add configurations to the folder resources/my-maven-module/restEndpoints or to subfolders.

my-maven-module/
└── src
    └── main
        └── resources
            └── my-maven-module
                └── restEndpoints
                    ├── foobar
                    │   └── johns-endpoint.yaml
                    └── larrys-endpoint.yaml

In the JCR configuration workspace

Add configurations to the folder /modules/my-custom-module/restEndpoints or to subfolders.

Node name

 modules

 my-custom-module

 restEndpoints

 super-endpoint

 foobar

 mega-endpoint