Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
This page explains Use the delivery endpoint, which can be used API to obtain JCR data as JSON.
The endpoint provides two resources to be called with HTTP
Mgnl get |
---|
The delivery endpoint must be configured via YAML. Its next version will allow multiple named configurations which can be distinguished by URL path parameter.
Table of Contents | ||||
---|---|---|---|---|
|
readNode
Returns one node by a given path including its properties and child nodes down to a certain depth.
Mgnl get |
---|
/delivery/{workspace}/v1/{path}
...
highlightColor | @default |
---|---|
multiple | false |
enableHeadingAttributes | false |
enableSorting | false |
enableHighlighting | false |
...
Parameter
...
Description
...
Data type
...
workspace
...
required
The name of the workspace.
...
String
...
path
...
required
The path relative to the rootPath
defined in the configuration
...
String
Get the node of the first component in the area main
of the page /travel/hello
.
Code Pro |
---|
curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/delivery/website/v1/travel/hello/main/0' \
-u superuser:superuser |
...
title | Click to see the resulting JSON |
---|
Code Pro | ||
---|---|---|
| ||
{
"@name": "0",
"@path": "/travel/hello/main/0",
"text": "<p>This is demo content - which was added to the travel demo after installation for test reasons.</p>\n",
"constrainAspectRatio": "false",
"imagePosition": "below",
"headlineLevel": "small",
"headline": "Welcome to this demo content to test REST",
"image": "jcr:795449d2-6c16-402e-9e8a-bbb101fe22bb",
"@nodes": []
} |
queryNodes
Returns a list of nodes matching a query which is composed by the given query parameters.
Mgnl get |
---|
/delivery/{workspace}/v1?param1=value1¶m2=value2&...
You can use any of the optional query parameters or none.
...
highlightColor | @default |
---|---|
multiple | false |
enableHeadingAttributes | false |
enableSorting | false |
enableHighlighting | false |
...
Parameter
...
Description
...
Parameter type
...
Data type
...
workspace
...
required
The name of the workspace.
...
path
...
String
...
nodeTypes
...
optional
Comma-separated string of primary node types.
...
query
...
String
...
q
...
optional
Text to search (full-text search).
...
query
...
String
...
orderBy
...
optional
The properties to order the nodes. Example: mgnl:lastModified desc,title asc*
...
query
...
String
...
optional (default=0)
Starting position in a result list (to use for pagination)
...
limit
optional ( default: as set in YAML configuration)
...
query
...
Integer
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.
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.
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. |
*) Note that special characters such as a space (
) must be encodeded 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
...
Search nodes in the workspace tours
which contain the keyword vietnam, order the result descending by the property location
and restrict the limit to one.
Code Pro |
---|
curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/delivery/tours/v1?q=vietnam&orderBy=location%20desc&limit=1' \
-u superuser:superuser |
...
title | Click to see the resulting JSON |
---|
Code Pro | ||||
---|---|---|---|---|
| ||||
[
{
"@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": []
}
] |
Note that the response above was created with a basic configuration without reference resloving. See lines 9-12 tour-types
. You can resolve this referenced nodes within the same REST request with reference resolving configuration.
...
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. (Future versions will allow multiple configurations which can be distinguished via URL parameter.)
Add the configuration to the folder restEndpoints
in a light module or within src/main/resources/<module-name>/restEndpoints
in a Magnolia Maven module.
Code Pro | ||||
---|---|---|---|---|
| ||||
class: info.magnolia.rest.delivery.jcr.JcrDeliveryEndpointDefinition
implementationClass: info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpoint
params:
website:
depth: 3
includeSystemProperties: false
nodeTypes:
- mgnl:page
- mgnl:area
- mgnl:component
rootPath: /
dam:
depth: 1
includeSystemProperties: false
nodeTypes:
- mgnl:asset
- mgnl:folder
rootPath: /travel-demoe |
Properties:
...
required
Must be info.magnolia.rest.delivery.jcr.JcrDeliveryEndpointDefinition
or a subclass.
...
required
Must be info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpoint
or a subclass.
...
required
The map defining at least one ore more workspace parameters.
...
<workspace-name>
...
required
The name of the JCR workspace to deliver content from. You define as many workspaces as you need.
You define one workspace with the below properties. (The definiton class is
Javadoc resource link | ||||
---|---|---|---|---|
|
...
nodeTypes*
...
required
An list of allowed node types.
...
depth*
...
optional (default=0)
The depth of subnodes to shwo in the result
...
includeSystemProperties
...
optional (default=true)
Whether the result should show the system properties.
...
rootPath
...
required
The root path of this endpoint. Path information when requesting the endpoint is added to this path.
...
bypassWorkspaceAcls
optional (default=false)
Note |
---|
When set to true JCR - security is bypassed. Use with care and for development reasons only! |
...
limit*
...
optional (default=10)
The number of nodes (of level 0) in the result. Only used in queryNodes
method.
*) These properties can be overridden when calling queryNodes
with a request parameter.
...
A node may contain references to other nodes. You can extend the configuration to force it to resolve referenced nodes per workspace with the property references
Code Pro | ||||
---|---|---|---|---|
| ||||
class: info.magnolia.rest.delivery.jcr.JcrDeliveryEndpointDefinition
implementationClass: info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpoint
params:
tours:
depth: 1
includeSystemProperties: false
nodeTypes:
- mgnl:content
- mgnl:folder
rootPath: /
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 | ||||
---|---|---|---|---|
|
...
propertyName
...
referenceResolver
...
The reference resolver definition for this reference, its definition class is
Javadoc resource link | ||||
---|---|---|---|---|
|
...
implementationClass
...
A class implementing
Javadoc resource link | ||||
---|---|---|---|---|
|
Current implementations:
Javadoc resource link | ||||
---|---|---|---|---|
|
...
targetWorkspace
...
title | Click here see a response with resolved references |
---|
Code Block | ||
---|---|---|
| ||
[
{
"@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ä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",
"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",
"displayName_de": "Kultur",
"icon": "jcr:58c420b6-fa30-4578-8af0-c062ba51e5fb",
"displayName": "Cultural",
"image": "jcr:a792164f-5a2a-4708-b3c8-62b48a578200",
"@nodes": []
},
"@nodes": [
"offPath",
"cultural"
]
},
"@nodes": [
"tourTypes"
]
}
] |
...
.