This page describes Use the delivery endpoint for obtaining API to obtain JCR data as JSON. The endpoint provides two resources that can be called with HTTP
. The endpoint has to be configured via YAML, which enables its customization.readNode
Returns one node by a given path, including its properties and child nodes down to a certain depth.
Request URL
/delivery/{endpointPrefix}/v1/{path}
Parameters
...
highlightColor | @default |
---|
multiple | false |
---|
enableHeadingAttributes | false |
---|
enableSorting | false |
---|
enableHighlighting | false |
---|
...
Parameter
...
Description
...
Data type
...
endpointPrefix
...
required
The name of an endpoint prefix as configured in YAML. Also can 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.
Code Pro |
---|
curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/delivery/website/v1/travel/about/main/00' \
-u superuser:superuser |
Expand |
---|
title | Click to see the resulting JSON |
---|
|
Code Pro |
---|
| {
"@name": "00",
"@path": "/travel/about/main/00",
"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> ",
"text_de": "<p>Wir sind eine unabhängige Reiseagentur mit Rundumservice.</p>\n<p>Wir bieten einzigartige Reisen für jeden Kontinent der Erde an. Lassen Sie sich inspirieren und buchen Sie Ihre Reise bei uns, um Erfahrungen zu machen, die Ihnen für immer in Erinnerung bleiben werden.</p> ",
"jcr:createdBy": "admin",
"headline_de": "Über Magnolia Travels",
"mgnl:lastActivatedBy": "superuser",
"mgnl:template": "travel-demo:components/jumbotron",
"mgnl:lastActivated": "2015-10-27T13:50:52.396+0100",
"jcr:created": "2017-10-31T11:53:44.169+0100",
"mgnl:created": "2015-02-02T20:23:37.199+0100",
"imagePosition": "below",
"headlineLevel": "small",
"mgnl:createdBy": "superuser",
"jcr:uuid": "01db6fc1-78af-4284-adf0-8c997309df6a",
"headline": "About Magnolia Travels",
"mgnl:lastModified": "2015-06-18T11:08:06.983+0200",
"mgnl:activationStatus": "true",
"jcr:primaryType": "mgnl:component",
"mgnl:lastModifiedBy": "superuser",
"@nodes": []
} |
The result is based on the basic configuration . |
queryNodes
Returns a list of nodes matching a query composed of the given query parameters. You also can apply filters to the query.
Request URL
/delivery/{endpointPrefix}/v1?param1=value1¶m2=value2&...
Use any of the optional query parameters or none.
Parameters
...
highlightColor | @default |
---|
multiple | false |
---|
enableHeadingAttributes | false |
---|
enableSorting | false |
---|
enableHighlighting | false |
---|
...
Parameter
...
Description
...
Parameter type
...
Data type
...
endpointPrefix
...
required
The name of an endpoint prefix as configured in YAML. Also can 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 have to encode it manually or with an additional tool. Example: orderBy=title%20asc
...
query
...
String
...
The start position in a result list (for pagination)
...
limit
...
optional, default is as set in YAML configuration
The number of nodes displayed in a pagequery. Used together with offset
for pagination.
...
query
...
Integer
...
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, you can combine filters with AND
operator. See filter options.
...
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.
Hide block |
---|
Format and operators The filter has the following format: property[operator]=value . For example, https://example.com/.rest/delivery/pages/v1?title[like]=tour . If no operator is provided, eq is used by default. Supported operators: eq means =
ne means <> lt means < gt means > lte means <= gte means >= like means LIKE in means IN not-in means NOT IN
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
For filtering by time, only two formats (ISO 8601 based) are accepted: - Date:
yyyy-MM-dd - Datetime:
yyyy-MM-dd'T'HH:mm:ss.SSSXXX (Example: 2018-01-01 2018-01-11T10:26:47.438+07:00 )
|
Property filter
Filter for a property of the node. Thev value for the property must be an exact match.
Mgnl mini code snippet |
---|
|
author=Magnolia%20Travels |
@name property filter
Filter for the node name.
Mgnl mini code snippet |
---|
|
@name=travel |
@ancestor filter
Filter for ancestor nodes of a provided path. The path must be absolute on the given workspace of the given workspace prefix.
Mgnl mini code snippet |
---|
|
@ancestor=/travel/about/careers/marketing-associate |
Using OR |
to provide multiple filter values
One filter can have multiples possible values which must match.
Mgnl mini code snippet |
---|
|
@name=travel|about |
...
Search nodes in the tours
workspace which contain the keyword vietnam . Return the results in descending order by the location
property and restrict the limit to one.
Code Pro |
---|
curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/delivery/trips/v1?q=vietnam&orderBy=location%20desc&limit=1' \
-u superuser:superuser |
Expand |
---|
title | Click to see the resulting JSON |
---|
|
The result is based on the basic configuration. Code Pro |
---|
language | js |
---|
linenumbers | true |
---|
| {
"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",
"tourTypes": [
"415025c6-e4b5-4506-9384-34f428a52104",
"e007e401-1bf8-4658-8293-b9c743784264"
],
"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ähigkeit zum Wandel. Dies wird nirgends deutlicher als in Ho-Chi-Minh-Stadt. Die am Saigon-Fluss gelegene Großstadt ist das perfekte Beispiel für das Nebeneinander von Fortschritt und Tradition. Prächtige Kolonialbauten stehen neben modernen Wolkenkratzern, während sich japanische Autos mit Fahrradrikschas die stark befahrenen Straßen teilen. Wir bringen Sie nicht nur zu den wichtigsten Sehenswürdigkeiten, sondern zeigen Ihnen auch die verborgenen Geschichten, die erklären können, was Vietnam zu dem macht, was es heute ist, und wohin es geht.</p>\n<p>Eine zweitägige Tour durch das Mekong-Delta (Vietnamesisch: Đồng Bằng Sông Cuu Long „Flussdelta der neun Drachen“) taucht Sie in ein Labyrinth des Lebens auf dem Wasser ein, in dem alles auf Booten geschieht, selbst die lokalen Märkte, die Tag für Tag durch ein Floß der Boote der Händler gebildet werden. Wir fahren weiter zur Küstenstadt Vung Tau, um dort im Phuong-Distrikt zu entspannen und wie die Einheimischen zu schwimmen.<br /> Während wir dort sind, besuchen wir den berühmten Weißen Palast, die alte historische Kolonialvilla des franzö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’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’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’s going.</p>\n<p>A two day tour of the Mekong delta (Vietnamese: Đồng bằng Sông Cửu Long "Nine Dragon river delta") 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’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’ll visit the storied White Palace, the historical old colonial villa of the french governor.</p>\n<p>Along the way, you’ll eat some of the finest food you’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",
"@nodes": []
}
]
} |
|
Search a tour and filter with the description
property (Get photobombed by a Sea Turtle).
Code Block |
---|
curl -X GET \
'http://localhost:8080/magnoliaAuthor/.rest/delivery/trips/v1?description=Get%20photobombed%20by%20a%20Sea%20Turtle' \
-u superuser:superuser |
Expand |
---|
title | Click to see the resulting JSON |
---|
|
Code Pro |
---|
language | js |
---|
linenumbers | true |
---|
| {
"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ührt zum weltberühmten Tiger Beach in den Gewässern vor den Bahamas. Dieser spektakuläre Ort ist einmalig in der Welt. Magnolia Travels garantiert Ihnen eine der einzigstartigen Unterwasser-Erfahrungen überhaupt. Umgeben vom kristallblauen Wasser der Bahamas und perlweißem Sand können Sie Ammenhaie, Riffhaie, Zitronenhaie und Tigerhaie beobachten. Bringen Sie Ihre Kamera mit, es gibt auf dieser Reise keinen Mangel an großartigen Foto- oder Videogelegenheiten. </p>\n<p>Auf dieser Expedition haben Sie Gelegenheit, mit unseren entzückenden und berühmten Tigerhai-„Supermodels“ von Angesicht zu Angesicht zu tauchen: Emma, Baby Cakes, Tanya, Begonia und Mini-T. Unsere „Supermodel“ werden Ihnen dabei helfen, einige der weltweit besten Hai-Fotos zu schießen. Sie lieben es, für die Kamera zu lächeln!</p>\n<p>Natürlich wäre keine Reise auf die Bahamas vollständig ohne Tauchen in den umwerfenden und vielfarbigen Riffen. Sie sind von einer Fülle kleiner und großer Meereslebewesen umgeben; Schönheit und Wunder dieses vibriendenden Ökosystems lassen Sie verstummen. Karibische Riffhaie, große Zackenbarsche, Muränenaale und viele andere Fische wetteifern um Ihre Aufmerksamkeit, während Sie über vielfältige Korallenarten, wellenförmige Seefächer und eine bunte Anordnung von Schwä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. Amidst the crystal blue Bahamian water and powder white sand, you will experience Nurse, Reef, Lemon and Tiger sharks up close and personal. Bring your camera, there is no shortage of great photo or video opportunities on this trip. </p>\n<p>On this expedition you will have the opportunity to dive face-to-face with our lovely and famous Tiger shark “supermodels”: Emma, Baby Cakes, Tanya, Begonia & Mini-T. Our “supermodels” will help you produce some of the world’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. 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. 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. 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": []
}
]
} |
The result is based on the basic configuration. |
Search all ancestor nodes of the page /travel/about/careers/marketing-associate from the website workspace
Code Block |
---|
curl -X GET \
'http://localhost:8080/magnoliaAuthor/.rest/delivery/website/v1?@ancestor=/travel/about/careers/marketing-associate' \
-u superuser:superuser |
...
MultiExcerptName | configuration |
---|
The delivery endpoint requires a YAML configuration; otherwise, it cannot deliver content. Version 2.0 of the magnolia-rest-content-delivery
module can have only one configuration. You can decorate the definition. Future versions will allow multiple configurations which can be distinguished via a URL parameter.
Add the configuration to the restEndpoints
folder in a light module or within src/main/resources/<module-name>/restEndpoints
in a Magnolia Maven module.
...
Code Pro |
---|
language | yaml |
---|
title | 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:
...
required
Must be info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpointDefinition
or a subclass.
...
optional default=info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpoint
Must be info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpoint
or a subclass.
...
required
The map defining at least one or more endpoint prefixes.
...
<endpointPrefix>
...
required
Defines an endpoint prefix where requests will be routed and handled according to the associated workspace parameters below.
The value can be an arbitrary name (no special characters!) - 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
...
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
Note |
---|
If set to true , JCR security is bypassed. Use this with care and for development reasons 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.
This REST resource is customizable and flexible to use.
Two versions of the delivery endpoint exist. Both versions can resolve references to nodes of other JCR workspaces. But only version 2 can deliver localized content.
Delivery endpoint v2
Version 2 was introduced with Magnolia REST 2.1 and provides more flexibility. You can use it to define multiple endpoint configurations, deliver localized content and resolve references to nodes of other workspaces including assets and asset renditions.
See Delivery endpoint API v2.
Delivery endpoint v1
Version 1 was introduced with Magnolia REST 2.0. You can configure a single endpoint for your project.
Note |
---|
Version 1 is deprecated, but you can still use it if required. We recommend you use the newer version 2. |
See Delivery endpoint API v1.
...
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.
Code Pro |
---|
language | yaml |
---|
linenumbers | true |
---|
|
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
:
...
<reference-name>
...
An arbitrary name for a
Javadoc resource link |
---|
className | info.magnolia.rest.reference.ReferenceDefinition |
---|
renderType | asynchronous |
---|
|
....
propertyName
...
referenceResolver
...
The reference resolver definition for this reference. Its definition class is
Javadoc resource link |
---|
className | info.magnolia.rest.reference.ReferenceResolverDefinition |
---|
renderType | asynchronous |
---|
|
....
implementationClass
...
A class implementing
Javadoc resource link |
---|
className | info.magnolia.rest.reference.ReferenceResolverDefinition |
---|
renderType | asynchronous |
---|
|
.Current implementations:
Javadoc resource link |
---|
className | info.magnolia.rest.reference.jcr.UuidReferenceResolver |
---|
renderType | asynchronous |
---|
|
....
targetWorkspace
...
title | Click to see a response with resolved references |
---|
...
...