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 1 for obtaining JCR data as JSON. The endpoint provides two methods that can be called with HTTP GET. You can only create a single configuration that is required to use it.

Version 1 of the delivery endpoint is deprecated. We recommend using version 2 instead.

Methods

Read node

Returns one node by a given path, including its properties and child nodes down to a certain depth.

Request URL

GET <magnolia-base-path>/.rest/delivery/{endpointPrefix}/v1/{path}

Parameters

Parameter

Description

Data type

endpointPrefix

required

The name of an endpoint prefix as configured. May also be a real workspace name.

String

path

required

The path relative to the rootPath defined in the configuration.

String

Example

Get the node of the first component in the main area of the /travel/about page.

curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/delivery/website/v1/travel/about/main/00' \
-u superuser:superuser

 Click to see the resulting JSON

{
  "@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> ",
  "text_de": "<p>Wir sind eine unabh&auml;ngige Reiseagentur mit Rundumservice.</p>\n<p>Wir bieten einzigartige Reisen f&uuml;r jeden Kontinent der Erde an. Lassen Sie sich inspirieren und buchen Sie Ihre Reise bei uns, um Erfahrungen zu machen, die Ihnen f&uuml;r immer in Erinnerung bleiben werden.</p> ",
  "headline_de": "Über Magnolia Travels",
  "imagePosition": "below",
  "headlineLevel": "small",
  "headline": "About Magnolia Travels",
  "@nodes": []
}

This result is based on the basic configuration.

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/delivery/{endpointPrefix}/v1?param1=value1&param2=value2&... 

Use any of the optional query parameters or none.

Parameters

Parameter

Description

Parameter type

Data type

endpointPrefix

required

The name of an endpoint prefix as configured. May also be a real workspace name.

path

String

q

optional

A search phrase (full-text search).

query

String

orderBy

optional

The properties by which to order the nodes.

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%20asc

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



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:

https://example.com/.rest/delivery/pages/v1?title[like]=tour
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

@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:

    https://example.com/.rest/delivery/pages/v1?mgnl:created[in]=2018-01-01~2018-02-01
  • 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

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

      curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/delivery/website/v1?mgnl:lastModified\[lte\]=2015-06-03' \
      -u superuser:superuser
      The brackets have been escaped with the backslash character ( \ ) for the command to work correctly in bash.

       Click to see the resulting JSON

      {
        "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-09T13:47:38.468+01:00",
          "mgnl:lastActivated": "2018-03-09T13:47:50.329+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": []
        }]
      }
      This result is returned for the following configuration:

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

      Please note that due to MGNLREST-170 - Getting issue details... STATUS , you have to send the following request to obtain the response shown above:

      curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/delivery/website/v1?mgnl:lastModified\[lte\]=2015-06-04' \
       -u superuser:superuser

    • Find webpages with either "Customer Experience Agent" or "Customer Experience Supervisor" as the title. This can be done in two ways:

      curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/delivery/website/v1?title=Customer%20Experience%20Agent|Customer%20Experience%20Supervisor' \
      -u superuser:superuser
      curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/delivery/website/v1?title\[like\]=Customer%20Experience%20%25' \
      -u superuser:superuser
      The brackets have been escaped with the backslash character ( \ ) for the command to work correctly in bash.

       Click to see the resulting JSON

      {
        "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",
            "title_de": "Kundenerlebnisvermittler",
            "@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",
            "title_de": "Kundenerlebnisteamleiter",
            "@nodes": []
          }
        ]
      }
      This result is returned for the following configuration:

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

      Due to the use of a wildcard character (%, URL encoded as %25) in the URL with the [like] filter, the number of results can potentially be higher. For example, if the website also contained a page called "Customer Experience Manager", it would be returned in the response.

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

      curl -X GET \
      'http://localhost:8080/magnoliaAuthor/.rest/delivery/website/v1?@ancestor=/travel/about/careers' \
       -u superuser:superuser
       Click to see the resulting JSON

      {
        "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",
          "title_de": "Kundenerlebnisvermittler",
          "@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",
          "title_de": "Kundenerlebnisteamleiter",
          "@nodes": []
        }, {
          "@name": "marketing-associate",
          "@path": "/travel/about/careers/marketing-associate",
          "@id": "f19c60f2-3049-4883-a170-4bf65e3abb91",
          "@nodeType": "mgnl:page",
          "hideInNav": "false",
          "title": "Marketing Associate",
          "title_de": "Marketingmitarbeiter/in",
          "@nodes": []
        }]
      }
      This result is returned for the following configuration:

      class: info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpointDefinition
      params:
        website:
          rootPath: /
          includeSystemProperties: false
          nodeTypes:
            - mgnl:page
    • Find nodes in the tours workspace that contain the keyword "beach". Return the results in the descending order based on the location property and restrict the number of results to three:

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

       Click to see the resulting JSON

      {
        "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_de": "<p>Wenn Sie &bdquo;Amazonas&ldquo; h&ouml;ren, denken Sie wahrscheinlich an einen tiefen Dschungel. Nun, dieses bemerkenswert gut versteckte Strandparadies liegt mitten drin. Alter do Ch&atilde;o liegt am Rio Tapaj&oacute;s, einem Nebenfluss des m&auml;chtigen Amazonas, der so breit ist, dass Sie nicht einmal das gegen&uuml;berliegende Ufer sehen k&ouml;nnen. Es gibt viel Natur in der Umgebung, die zu Fu&szlig; erkundet werden kann; die Bucht am See ist voller gem&uuml;tlicher Strandrestaurants und Bars, ideal f&uuml;r ein Chill-out nach dem Schwimmen. &nbsp;</p>\n<p>Keine Angst vor Krokodilen hier, aber es gibt einige Stachelrochen, auf die man aufpassen sollte.&nbsp; Sie beginnen Ihr Abenteuer auf der zweit&auml;gigen Bootsfahrt von Manaus (Hauptstadt des Amazonas) nach Santar&eacute;m, aber achten Sie darauf, Ihre eigene H&auml;ngematte (und etwas Seil) oder einfach nur etwas Extra-Kleingeld f&uuml;r die Bar mitzubringen!</p>\n<p>W&auml;hrend Sie dort sind, werden Sie feststellen, dass es viel mehr zu tun gibt, als an den herrlichen Str&auml;nden herumzuh&auml;ngen. Die Stadt liegt am Eingang zur Lagune Lago Verde, Heimat vieler Tiere Amazoniens und der perfekte Ort f&uuml;r eine Kanufahrt. Wir unternehmen auch Touren in die sch&ouml;ne Floresta Nacional do Rio Tapaj&oacute;s und Rio Arapiuns.</p> ",
            "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> ",
            "description_de": "Ein Amazonas-Strandurlaub",
            "destination": [
              "bed2e297-199c-4dc8-90cd-54ad3cb4221b"
            ],
            "duration": "14",
            "name_de": "Strand Paradies in Brasilien",
            "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_de": "<p>Stellen Sie sich vor, dass Sie auf den Spuren der Forscher, Missionare und Soldaten unterwegs sind, die Amerika zu dem gemacht haben, was es heute ist. Entdecken Sie den ber&uuml;hmten Camino Real (Die k&ouml;nigliche Stra&szlig;e), der auf dem alten Weg beruht, der die spanischen Missionen, Pueblos und Milit&auml;rposten miteinander verband.</p>\n<p>Wir starten in Seattle und gehen s&uuml;dw&auml;rts nach Oregon und schlie&szlig;lich nach Kalifornien, wo wir auf die Str&auml;nde des Highway 1 treffen. Die Reise wird von Geschichte und traumhafter durchdrungen sein, aber es wird auch jede Menge Zeit f&uuml;r Spa&szlig; geben, mit einigen tollen Strandaktivit&auml;ten am Ende der Reise.</p>\n<p>&nbsp;</p> ",
            "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> ",
            "description_de": "Familienreisen in den USA",
            "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",
            "name_de": "Westküste - Highway 101",
            "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_de": "<p>Diese einzigartige Reise bringt Ihnen einige wirkliche Einblicke in das Leben auf der arabischen Halbinsel, gibt Ihnen aber auch genug Zeit, die Sonne zu genie&szlig;en. Sie beginnen Ihre Reise im altert&uuml;mlichen Oman, wo das Leben fast genauso seinen Gang geht wie schon viele Jahrhunderte zuvor. Sie besuchen den faszinierenden Souk von Maskat, um dort um handgefertigtes Silberzeug und T&ouml;pfe zu feilschen. Danach k&ouml;nnen Sie einen Spaziergang entlang des belebten Hafens unternehmen und einige der verwinkelten Gassen der Stadt besuchen. Runden Sie den Tag ab und entspannen Sie sich in einem Liegestuhl im Grand Hyatt, von dem aus Sie Blick auf den Strand von Oman haben.</p>\n<p>In Dubai besuchen wir einige der Wunder der Stadt wie Burj al Khalifa, das h&ouml;chste Geb&auml;ude der Welt, und den Dubai Mall, das gr&ouml;&szlig;te Einkaufszentrum Welt mit seinem herrlichen Aquarium. Aber nach all dem Sightseeing gibt es nichts Besseres als Entspannung am Strand des luxuri&ouml;sen Atlantis Hotel auf der Palm Jumeirah, eine vom Menschenhand geschaffene Insel in Form einer Palme. Magnolia Travels wird daf&uuml;r sorgen, das dies ein Urlaub ist, den Sie nie vergessen werden!</p> ",
            "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> ",
            "description_de": "Ein unvergessliches Erlebnis im Arabischen Golf",
            "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",
            "name_de": "Dubai und Oman",
            "image": "jcr:7eeb9a4f-72ef-43f4-a392-5c1916b31e3a",
            "@nodes": []
          }
        ]
      }

      This result is based on the basic configuration.

      Note that in this example, the endpoint prefix is called trips but the workspace mapped is called tours.

    • Find a tour with the description "Get photobombed by a Sea Turtle":

      curl -X GET \
      'http://localhost:8080/magnoliaAuthor/.rest/delivery/trips/v1?description=Get%20photobombed%20by%20a%20Sea%20Turtle' \
      -u superuser:superuser
       Click to see the resulting JSON

      {
        "results": [
          {
            "@name": "Scuba-Diving-in-Bahamas--famed-Tiger-Beach",
            "@path": "/magnolia-travels/Scuba-Diving-in-Bahamas--famed-Tiger-Beach",
            "isFeatured": "true",
            "name": "Scuba Diving at Tiger Beach",
            "description": "Get photobombed by a Sea Turtle",
            "location": "Miami, USA",
            "tourTypes": [
              "d2245867-ecaa-4b4e-8743-e0c939be68b7",
              "eaf9a648-fae1-48ae-a293-69bed874f159"
            ],
            "author": "Magnolia Travels",
            "body_de": "<p>Unsere beliebteste aktive Tour f&uuml;hrt zum weltber&uuml;hmten Tiger Beach in den Gew&auml;ssern vor den Bahamas. Dieser spektakul&auml;re Ort ist einmalig in der Welt. Magnolia Travels garantiert Ihnen eine der einzigstartigen Unterwasser-Erfahrungen &uuml;berhaupt. Umgeben vom kristallblauen Wasser der Bahamas und perlwei&szlig;em Sand k&ouml;nnen Sie Ammenhaie, Riffhaie, Zitronenhaie und Tigerhaie beobachten. Bringen Sie Ihre Kamera mit, es gibt auf dieser Reise keinen Mangel an gro&szlig;artigen Foto- oder Videogelegenheiten. &nbsp;</p>\n<p>Auf dieser Expedition haben Sie Gelegenheit, mit unseren entz&uuml;ckenden und ber&uuml;hmten Tigerhai-&bdquo;Supermodels&ldquo; von Angesicht zu Angesicht zu tauchen:&nbsp; Emma, Baby Cakes, Tanya, Begonia und Mini-T. Unsere &bdquo;Supermodel&ldquo; werden Ihnen dabei helfen, einige der weltweit besten Hai-Fotos zu schie&szlig;en. Sie lieben es, f&uuml;r die Kamera zu l&auml;cheln!</p>\n<p>Nat&uuml;rlich w&auml;re keine Reise auf die Bahamas vollst&auml;ndig ohne Tauchen in den umwerfenden und vielfarbigen Riffen. Sie sind von einer F&uuml;lle kleiner und gro&szlig;er Meereslebewesen umgeben;&nbsp; Sch&ouml;nheit und Wunder dieses vibriendenden &Ouml;kosystems lassen Sie verstummen. Karibische Riffhaie, gro&szlig;e Zackenbarsche, Mur&auml;nenaale und viele andere Fische wetteifern um Ihre Aufmerksamkeit, w&auml;hrend Sie &uuml;ber vielf&auml;ltige Korallenarten, wellenf&ouml;rmige Seef&auml;cher und eine bunte Anordnung von Schw&auml;mmen gleiten. Beginnen Sie noch heute, mit uns Ihre Erinnerungen zu gestalten!</p> ",
            "body": "<p>Our most popular active tour is to the world-famous Tiger Beach in the waters off the Bahamas. This spectacular location is unlike any other in the world. Magnolia Travels guarantees you will have one of the most unique underwater experiences ever. &nbsp;Amidst the crystal blue Bahamian water and powder white sand, you will experience Nurse, Reef, Lemon and Tiger sharks up close and personal. &nbsp;Bring your camera, there is no shortage of great photo or video opportunities on this trip. &nbsp;</p>\n<p>On this expedition you will have the opportunity to dive face-to-face with our lovely and famous Tiger shark &ldquo;supermodels&rdquo;: &nbsp;Emma, Baby Cakes, Tanya, Begonia &amp; Mini-T. &nbsp;Our &ldquo;supermodels&rdquo; will help you produce some of the world&rsquo;s best shark photography. They love to smile for the camera!</p>\n<p>Of course, no trip to the Bahamas would be complete without diving the dazzling and colorful reefs. &nbsp;Surrounded by an abundance of marine life, both large and small, you will be in awe of the beauty and wonder of this vibrant ecosystem. &nbsp;Caribbean Reef sharks, large groupers, moray eels and numerous fish will compete for your attention as you hover above the multiple species of coral, undulating sea fans, and colorful array of sponges. &nbsp;Start making your memories with us today!</p> ",
            "description_de": "Lassen Sie sich von einer Meeresschildkröte überraschen, die plötzlich auf Ihrem Foto erscheint",
            "destination": [
              "ed3dcd18-78af-46df-a9e1-bc732479f2e7"
            ],
            "duration": "14",
            "name_de": "Tauchen am Tiger Beach",
            "image": "jcr:795449d2-6c16-402e-9e8a-bbb101fe22bb",
            "@nodes": []
          }
        ]
      }

      This result is based on the basic configuration.

      Note that in this example, the endpoint prefix is called trips but the workspace mapped is called tours.

Configuration

The delivery endpoint requires a configuration, or it cannot deliver content. Version 1 of the delivery endpoint can only have one configuration. You can decorate the definition.

Add the configuration to the restEndpoints folder in a light module, within src/main/resources/<module-name>/restEndpoints in a Magnolia Maven module or as JCR in the configuration workspace.

Basic configuration

my-lightmodule/restEndpoints /my-endpoint.yaml
class: info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpointDefinition
params:
  website:
    depth: 2
    nodeTypes:
      - mgnl:page
      - mgnl:area
      - mgnl:component
    childNodeTypes:
      - mgnl:area
      - mgnl:component
    rootPath: /
  trips:
    workspace: tours
    includeSystemProperties: false

Properties:

class

required

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

implementationClass

optional, default is info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpoint

Must be info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpoint or a subclass.

params

required

The map defining at least one or more endpoint prefixes.

<endpointPrefix>

required

Defines an endpoint prefix where requests are routed and handled according to the associated workspace parameter below.

The value can be an arbitrary name (no special characters allowed), or it can be a real workspace name. If it is not a real workspace name, you must provide the sub property workspace.

workspace

optional

The name of the JCR workspace to deliver content from.

Must be set if the parent <endpointPrefix> is not a real workspace name.

nodeTypes

optional, default is mgnl:content

A list of allowed node types for depth-0 nodes. mgnl:folder is ignored deliberately.

childNodeTypes

optional, default is mgnl:contentNode

A list of allowed node types for child nodes.

depth

optional, default is 0

The depth of child nodes to display in the result.

includeSystemProperties

optional, default is true

Specifies whether the result should show system properties.

rootPath

optional

The root path of this endpoint.

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

bypassWorkspaceAcls

optional, default is false

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

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.

Reference resolving configuration

A node may contain references to other nodes. With the references property, you can extend the configuration to force it to resolve the referenced nodes per workspace.

class: info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpointDefinition
params:
  trips:
    workspace: tours
    includeSystemProperties: false
    references:
      tour-types:
        propertyName: tourTypes
        referenceResolver:
          implementationClass: info.magnolia.rest.reference.jcr.UuidReferenceResolver
          targetWorkspace: category

Properties of references:

referencesA map which contains at least one reference definition.

<reference-name>

An arbitrary name for a ReferenceDefinition.

propertyName

The name of the JCR property which stores the reference. It can be a multi-value property.

referenceResolver

The reference resolver definition for this reference. Its definition class is ReferenceResolverDefinition.

implementationClass

A class implementing ReferenceResolverDefinition.

Current implementations: UuidReferenceResolver.

targetWorkspace

The name of the workspace where the referenced node resides.

 Click to see a response with resolved references
{
  "results": [
    {
      "@name": "Vietnam--Tradition-and-Today",
      "@path": "/magnolia-travels/Vietnam--Tradition-and-Today",
      "isFeatured": "true",
      "name": "Vietnam: Tradition and Today",
      "description": "Discover the culture and everyday treasures of a rising phoenix",
      "location": "Ho Chi Minh City, Vietnam",
      "author": "Magnolia Travels",
      "body_de": "<p>Vietnam ist eine der exotischsten und kulturreichsten Destinationen weltweit. Als Juwel unter Juwelen bietet es dem Besucher schillernde Vielfalt. Doch was die meisten so faszinierend finden, ist seine F&auml;higkeit zum Wandel. Dies wird nirgends deutlicher als in Ho-Chi-Minh-Stadt. Die am Saigon-Fluss gelegene Gro&szlig;stadt ist das perfekte Beispiel f&uuml;r das Nebeneinander von Fortschritt und Tradition. Pr&auml;chtige Kolonialbauten stehen neben modernen Wolkenkratzern, w&auml;hrend sich japanische Autos mit Fahrradrikschas die stark befahrenen Stra&szlig;en teilen. Wir bringen Sie nicht nur zu den wichtigsten Sehensw&uuml;rdigkeiten, sondern zeigen Ihnen auch die verborgenen Geschichten, die erkl&auml;ren k&ouml;nnen, was Vietnam zu dem macht, was es heute ist, und wohin es geht.</p>\n<p>Eine zweit&auml;gige Tour durch das Mekong-Delta (Vietnamesisch: Đồng Bằng S&ocirc;ng Cuu Long &bdquo;Flussdelta der neun Drachen&ldquo;) taucht Sie in ein Labyrinth des Lebens auf dem Wasser ein, in dem alles auf Booten geschieht, selbst die lokalen M&auml;rkte, die Tag f&uuml;r Tag durch ein Flo&szlig; der Boote der H&auml;ndler gebildet werden. Wir fahren weiter zur K&uuml;stenstadt Vung Tau, um dort im Phuong-Distrikt zu entspannen und wie die Einheimischen zu schwimmen.<br /> W&auml;hrend wir dort sind, besuchen wir den ber&uuml;hmten Wei&szlig;en Palast, die alte historische Kolonialvilla des franz&ouml;sischen Gouverneurs.</p>\n<p>Unterwegs werden Sie mit das beste Essen zu sich nehmen, das Sie jemals gegessen haben und wir werden Ihnen eventuell sogar beibringen, wie es zubereitet wird.</p> ",
      "body": "<p>Vietnam is one of the world&rsquo;s most exotic and culturally rich destinations. A gem among gems, it offers dazzling diversity for visitors. Yet what most find so fascinating is its capacity for change. This is nowhere more evident than in Ho Chi Minh City. Set on the Saigon river, the capital is the perfect example of progress and tradition living side-by-side. Grand colonial buildings stand alongside modern skyscrapers while Japanese cars share the busy roads with cycle rickshaws.</p>\n<p>We won&rsquo;t just take you to the key sights, but also reveal the hidden stories that explain what makes Vietnam what it is today, and where it&rsquo;s going.</p>\n<p>A two day tour of the Mekong delta (Vietnamese: Đồng bằng S&ocirc;ng Cửu Long &quot;Nine Dragon river delta&quot;) will immerse you in a water-world maze where everything happens on the boats - even local markets which form every day from a raft of vendors boats. We&rsquo;ll continue to the coastal town of Vung Tau in the Phuong district to relax and swim like the locals do.</p>\n<p>While there we&rsquo;ll visit the storied White Palace, the historical old colonial villa of the french governor.</p>\n<p>Along the way, you&rsquo;ll eat some of the finest food you&rsquo;ve ever eaten, and we might even teach you to cook it too.</p> ",
      "description_de": "Entdecken Sie die Kultur und die alltäglichen Schätze eines Phoenix aus der Asche",
      "destination": [
        "7ec72c48-c33f-418e-b2ff-44cfb4bbb1f2"
      ],
      "duration": "14",
      "name_de": "Vielfältiges Vietnam",
      "image": "jcr:1044b3b8-30b1-48fe-8078-832b6cef8fb5",
      "tourTypes": {
        "@name": "tourTypes",
        "@path": "/magnolia-travels/Vietnam--Tradition-and-Today/@tourTypes",
        "offPath": {
          "@name": "offPath",
          "@path": "/tour-types/offPath",
          "body_de": "Auf einem großen Reisebus sitzen, Touristengerichte essen und Fotos vom Eiffelturm machen ist nicht Ihre Vorstellung vom Reisen. Sie möchten etwas Neues finden und die Dinge aus dem örtlichen Blickwinkel betrachten. Mit uns können Sie die örtlichen Juwelen entdecken, die die meisten Reisenden nie sehen. ",
          "body": "Riding on a big tour bus, eating tourist menus and taking pictures of the Eiffel Tower is not your idea of travelling. You want to find something new, and see things from a local point of view. With us, you can discover the local gems that most travellers never experience. ",
          "description_de": "Einzigartige Ferien abseits der ausgetretenen Pfade",
          "name": "offPath",
          "level": "level-1",
          "description": "Unique holidays that take you off the beaten track ",
          "displayName_de": "Abseits der Trampelpfade",
          "icon": "jcr:6d5d576a-79f9-48d9-b141-6682f2eef585",
          "displayName": "Off the Beaten Path",
          "image": "jcr:272f75b9-ed87-4e0b-8bf3-15db217ba897",
          "@nodes": []
        },
        "cultural": {
          "@name": "cultural",
          "@path": "/tour-types/cultural",
          "body_de": "Ferien sind für Erlebnisse da, um die bedeutendsten Orte der Welt zu entdecken. Egal ob Chinesische Mauer oder ägyptische Pyramiden, Sie möchten alles darüber wissen. Haben Sie schon einmal daran gedacht, die alten Tempel in Vietnam zu bereisen oder die gewundenen Gassen in Jerusalem? Wir organisieren die besten örtlichen Reiseführer und Hotels, damit Sie die ganze Kultur einfach nur in sich aufnehmen brauchen.",
          "body": "Holidays are for experiences, for discovering the greatest places in the world. Whether it’s the Great Wall of China or the Egyptian pyramids, you want to know all about them. And have you thought about visiting the ancient temples of Vietnam or the winding alleyways of Jerusalem?  We organize the best local guides and hotels, so you can just soak in all that culture.",
          "description_de": "Einmalige Erlebnisse",
          "name": "cultural",
          "level": "level-1",
          "description": "Experiences of a lifetime",
          "icon": "jcr:58c420b6-fa30-4578-8af0-c062ba51e5fb",
          "displayName_de": "Kultur",
          "displayName": "Cultural",
          "image": "jcr:a792164f-5a2a-4708-b3c8-62b48a578200",
          "@nodes": []
        },
        "@nodes": [
          "offPath",
          "cultural"
        ]
      },
      "@nodes": [
        "tourTypes"
      ]
    }
  ]
}