Delivery endpoint API v2
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.
To help you configure and try out the delivery scenarios mentioned on this page, we:
-
Use
delivery
as part of the endpoint path. Our webapps come with a pre-configured user role calledrest-anonymous
, which allows anonymous users to access the/.rest/delivery/*
path. -
Set the
bypassWorkspaceAcls
property totrue
in all endpoint configurations. Otherwise, you would have to use the Security app and configure an access control list for the anonymous user to be able to access the nodes inside the various workspaces the delivery scenarios utilize.
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 |
---|---|---|
|
required The path relative to the |
|
Example
Get all component nodes of the main
area of the /travel/about
page.
curl 'http://localhost:8080/magnoliaAuthor/.rest/delivery/ep/travel/about/main'
{
"@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’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
bypassWorkspaceAcls: true
depth: 2
nodeTypes:
- mgnl:area
childNodeTypes:
- mgnl:component
Get children
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
The items in the response are returned in their
natural (unsorted) order. See also the orderBy parameter in the query nodes method.
|
Examples
-
Get child nodes in the root of the
ep
endpoint:curl "http://localhost:8080/magnoliaAuthor/.rest/delivery/ep/@nodes"
[ { "@name": "travel", "@path": "/travel", "@id": "b06b82a2-74b0-4994-8015-028c4fd60716", "@nodeType": "mgnl:page", "position": "bottom", "header": "Cookies are used on this website!", "layout": "block", "readMoreLinkexternal": "https://cookiesandyou.com/", "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.", "link": "Learn more ...", "title": "Travel Home", "dismiss": "Got it!", "bannerbackground": "#000", "deny": "Decline cookies", "message": "This website uses cookies to ensure you get the best experience on our website.", "readMoreLink": "external", "complianceType": "info", "buttontext": "#fff", "buttonbackground": "#ef6155", "hideInNav": "false", "searchResultPage": "6df1ebd8-fc9d-4db3-8539-02829c56b9f2", "allow": "Allow cookies", "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 bypassWorkspaceAcls: true nodeTypes: - mgnl:page
-
Get child nodes in the root of the
/travel
page:curl "http://localhost:8080/magnoliaAuthor/.rest/delivery/ep/travel/@nodes"
[ { "@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 bypassWorkspaceAcls: true 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¶m2=value2&…
Use any of the optional query parameters or none.
Parameters
The parameters below are query parameters.
The <filter> option is not a parameter but acts as a filter for the response of the operation.
|
Parameter | Description | Data type | ||||
---|---|---|---|---|---|---|
|
optional A search phrase (full-text search). |
|
||||
|
optional The properties by which to order the nodes. As of Magnolia 6.2.6, sorting is case-insensitive. 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.
The results are returned unsorted if no |
|
||||
|
optional The start position in a result list (for pagination). Default is |
|
||||
|
optional The number of nodes displayed in a page query. Use together with |
|
||||
|
optional Allows you to retrieve and preview a specific version of a content item. The request URL must be formed with Example Let there be a page https://<domain>>/<webapp>/.rest/delivery/ep/fldr/p1 Provided two versions, https://<domain>>/<webapp>/.rest/preview/ep/fldr/pg1?version=1.0 https://<domain>>/<webapp>/.rest/preview/ep/fldr/pg1?version=1.1 |
|
||||
|
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 |
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
In some REST clients, you may need to URL-encode also the key in the filter parameter. The RFC standard called Uniform Resource Identifier (URI): Generic Syntax (https://tools.ietf.org/html/rfc3986#section-2.2) maintains that |
If data for a URI component would conflict with a reserved character’s purpose as a delimiter, then the conflicting data must be percent-encoded before the URI is formed.
- For example
-
http://localhost:8080/magnoliaAuthor/.rest/my-endpoint?description
%5B
like
%5D
=%25demonstration%25
Filter operators
Operator | Meaning | ||
---|---|---|---|
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
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 asString
. -
Use brackets to pass an operator, for example
[eq]
,[ne]
,[lt]
, and so on. -
For
in
andnot-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 asprice >= 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
REST delivery endpoint v2 filter 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 12, 2015:
curl 'http://localhost:8080/magnoliaAuthor/.rest/delivery/ep/?mgnl:lastModified[lte]=2015-06-12' --globoff
By using the option --globoff
you can specify URLs that contain the letters \{}[] without having them being interpreted by cURL itself.Endpoint:
ep
class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition workspace: website bypassWorkspaceAcls: true rootPath: / nodeTypes: - mgnl:page includeSystemProperties: true
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": "2019-09-25T08:49:30.320+02:00", "mgnl:lastActivated": "2019-09-25T08:49:35.482+02: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/delivery/ep" --data-urlencode "title[like]=%Customer%"
Use
--data-urlencode
and-g -G
to encode the request parameter values, if required.Endpoint:
ep
class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition workspace: website bypassWorkspaceAcls: true rootPath: / 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": "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/delivery/ep/?@ancestor=/travel/about/careers'
Endpoint:
ep
class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition workspace: website bypassWorkspaceAcls: true rootPath: / 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 keywordbeach
. Return the results in descending order based on thelocation
property and restrict the number of results to two:curl 'http://localhost:8080/magnoliaAuthor/.rest/delivery/ep/?q=beach&orderBy=location%20desc&limit=2'
Endpoint:
ep
class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition workspace: tours bypassWorkspaceAcls: true
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 “Amazon”, you probably think of a deep jungle. Well, this remarkably well hidden beach paradise is right in the middle of it. Alter do Chão lies on Rio Tapajós, a tributary to the mighty Amazon, which is so wide here that you can’t even see across to the far shore. There’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. </p>\n<p>No fear of crocodiles here, but there are some sting rays to watch out for. You’ll start your adventure on the two-day boat ride from Manaus (capital of the Amazon) to Santaré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’re here, you’ll discover there’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ó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", "name": "West Coast - Highway 101", "description": "Family travels in USA", "location": "Seattle, USA", "tourTypes": [ "17da160b-da66-4e09-9e31-5fd040880f4a" ], "author": "Magnolia Travels", "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'll kick off in Seattle and head south into Oregon and finally to California where we'll hit the beaches on California Highway 1. The trip will be infused with history and fabulous scenery, but there’ll be lots of time for fun, with some great beach activities at the end of the trip.</p> ", "destination": [ "ed3dcd18-78af-46df-a9e1-bc732479f2e7" ], "duration": "7", "image": "jcr:d44f783c-91ca-4b48-9533-ea4e147e13e9", "@nodes": [ ] } ] }
-
Find a tour with the word
Japan
in itsdescription
. Return only the variant in the German language:curl -g -G 'http://localhost:8080/magnoliaAuthor/.rest/delivery/ep?lang=de-DE' --data-urlencode "description[like]=%Japan%"
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.Endpoint:
ep
class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition workspace: tours bypassWorkspaceAcls: true
Response
{ "results": [ { "@name": "Kyoto", "@path": "/magnolia-travels/Kyoto", "@id": "b475f27e-2929-427b-9517-815118a3b36e", "@nodeType": "mgnl:content", "name": "Kyoto", "description": "Die natürliche Seite Japans", "location": "Kyoto, Japan", "tourTypes": [ "d2245867-ecaa-4b4e-8743-e0c939be68b7", "415025c6-e4b5-4506-9384-34f428a52104" ], "author": "Magnolia Travels", "body": "<p>Erleben Sie die Schönheit, die Kyoto durchdringt und umgibt. Kyoto ist berühmt für viele Dinge, darunter unzä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ärten, bevor wir einen Abstecher zu den Bergen in der Umgebung der Stadt machen. Sie werden es genießen, einen Tag im grünen Miyama und einen Tag mit Wandern in Shizuhara zu verbringen. Sie werden nie wieder wie bisher über Japan denken.</p> ", "destination": [ "7ec72c48-c33f-418e-b2ff-44cfb4bbb1f2" ], "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
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
like=%Erleben%
instead. Only this will return a result (click the link to expand to see
the actual result):
{
"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'll visit Tō-ji, Ginkaku-ji, Kōzan-ji and their remarkable gardens before venturing into the mountains that surround the city. You’ll enjoy a day spent in green Miyama and a day hiking in Shizuhara. You’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
bypassWorkspaceAcls: true
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/delivery/ep/?q=Erleben
which will also return a response where Erleben appears in the JCR
(endpoint configuration is same as the one above):
{
"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’s coast in the North Sea lie the remote, romantic Halligen islands. Here, you’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’s like a slow-motion race against erosion and rising oceans. Speaking of slow - you’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’ll be able to observe some rare birdlife. We’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 ‘crazy slope’ days out. Children will love the chance to drive their own sled, and snowballs and snowmen are possible any time of the day. You’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'll visit Tō-ji, Ginkaku-ji, Kōzan-ji and their remarkable gardens before venturing into the mountains that surround the city. You’ll enjoy a day spent in green Miyama and a day hiking in Shizuhara. You’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’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’s most important archaeological sites.</p>\n<p>From there, we’ll go by road to Jerash, often called the ‘Pompeii of the East’. 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": []
}]
}
For i18n features to work correctly, check that the fallback site has locales configured or extends a site definition with desired locales. |
Retrieving all language variants
You can also use all
as the value of the lang
property to retrieve all language variants of content. Compare below the three requests and responses issued against the ep
endpoint configured as follows:
class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
workspace: website
bypassWorkspaceAcls: true
rootPath: /travel/book-tour/
nodeTypes:
- mgnl:page
lang
set to all
http://localhost:8080/magnoliaAuthor/.rest/delivery/ep/?lang=all
{
"results": [
{
"@name": "meal",
"@path": "/travel/book-tour/meal",
"@id": "9b8ea1b2-a93f-4015-a822-84d730ca982a",
"@nodeType": "mgnl:page",
"hideInNav": "true",
"title": "Meal",
"title_de": "Menü",
"@nodes": [
]
},
{
"@name": "review",
"@path": "/travel/book-tour/review",
"@id": "17680c5a-82b2-49e8-b078-186b1ab9284d",
"@nodeType": "mgnl:page",
"hideInNav": "true",
"title": "Review",
"title_de": "Überprüfung",
"@nodes": [
]
},
{
"@name": "personal-details",
"@path": "/travel/book-tour/personal-details",
"@id": "829ee1ee-4a74-4fca-8dc1-87f473eedd32",
"@nodeType": "mgnl:page",
"hideInNav": "true",
"title": "Personal details",
"title_de": "Persönliche Angaben",
"@nodes": [
]
}
]
}
lang
not set
http://localhost:8080/magnoliaAuthor/.rest/delivery/ep/
{
"results": [
{
"@name": "meal",
"@path": "/travel/book-tour/meal",
"@id": "9b8ea1b2-a93f-4015-a822-84d730ca982a",
"@nodeType": "mgnl:page",
"hideInNav": "true",
"title": "Meal",
"@nodes": [
]
},
{
"@name": "review",
"@path": "/travel/book-tour/review",
"@id": "17680c5a-82b2-49e8-b078-186b1ab9284d",
"@nodeType": "mgnl:page",
"hideInNav": "true",
"title": "Review",
"@nodes": [
]
},
{
"@name": "personal-details",
"@path": "/travel/book-tour/personal-details",
"@id": "829ee1ee-4a74-4fca-8dc1-87f473eedd32",
"@nodeType": "mgnl:page",
"hideInNav": "true",
"title": "Personal details",
"@nodes": [
]
}
]
}
lang
set to de
http://localhost:8080/magnoliaAuthor/.rest/delivery/ep/?lang=de
{
"results": [
{
"@name": "meal",
"@path": "/travel/book-tour/meal",
"@id": "9b8ea1b2-a93f-4015-a822-84d730ca982a",
"@nodeType": "mgnl:page",
"hideInNav": "true",
"title": "Menü",
"@nodes": [
]
},
{
"@name": "review",
"@path": "/travel/book-tour/review",
"@id": "17680c5a-82b2-49e8-b078-186b1ab9284d",
"@nodeType": "mgnl:page",
"hideInNav": "true",
"title": "Überprüfung",
"@nodes": [
]
},
{
"@name": "personal-details",
"@path": "/travel/book-tour/personal-details",
"@id": "829ee1ee-4a74-4fca-8dc1-87f473eedd32",
"@nodeType": "mgnl:page",
"hideInNav": "true",
"title": "Persönliche Angaben",
"@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
class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
workspace: website
limit: 25
depth: 2
includeSystemProperties: true
nodeTypes:
- mgnl:page
childNodeTypes:
- mgnl:area
- mgnl:component
#references
Properties
Parameter | Description | ||
---|---|---|---|
|
required Must be |
||
|
optional If the property is not set, the
|
||
|
required The name of the JCR workspace to deliver content from. |
||
|
optional The root path of this endpoint.
|
||
|
optional A list of allowed node types for depth-0 nodes. Default is |
||
|
optional A list of allowed node types for child nodes. Default is |
||
|
optional Defines whether to include only the exact node type and ignore the sub types.
|
||
|
optional The depth of child nodes to include in each returned item. Default is
|
||
|
optional Specifies whether the result should show system properties. Default is |
||
|
optional List of system properties that should be returned in the response.
|
||
|
optional The number of nodes (of level
|
||
|
optional Default is
|
||
|
optional This property allows you to resolve referenced nodes.
|
||
|
optional Defines on how many levels the references should be considered and returned in a response if found. Default is |
||
|
optional The default setting eliminates resolving self-references into fully expanded nodes and thus creating reference cycles. If a self-reference is found, only the value of the @id property of the self-referencing node is returned instead. Default is |
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 theendpointPath
evaluated by the system .
Examples:
YAML file location | endpointPath |
---|---|
my-module/restEndpoints/my-endpoint.yaml |
|
my-module/restEndpoints/delivery/another-endpoint.yaml |
|
my-module/restEndpoints/delivery/another-endpoint_v3.yaml |
|
JCR node path in`configuration` workspace |
endpointPath |
/modules/my-custom-module/restEndpoints/super-endpoint |
|
/modules/my-custom-module/restEndpoints/delivery/mega-endpoint |
|
/modules/my-custom-module/restEndpoints/delivery/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.
Best practice
Put the delivery endpoint configurations under the delivery
subfolder.
This makes the endpoints easier to use because the default role
rest-anonymous
is already configured to allow web access to the
.rest/delivery/*
path.
In a light module
Add configurations to the folder restEndpoints
or to subfolders.
my-light-module/ └── restEndpoints ├── delivery │ └── another-endpoint.yaml └── my-endpoint.yaml