Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
Page History
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 | ||||
|---|---|---|---|---|
|
Methods
readNode
Returns one node by a given path including its properties and child nodes down to a certain depth.
Request URL
| Mgnl get |
|---|
/delivery/{workspace}/v1/{path}Parameters
...
| 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
Example
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": []
} |
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.
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. |
queryNodes
Returns a list of nodes matching a query which is composed by the given query parameters.
Request URL
| Mgnl get |
|---|
/delivery/{workspace}/v1?param1=value1¶m2=value2&... You can 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
...
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
*) 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
Example
Search nodes in the workspace tours which contain the keyword lake, 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=lake&orderBy=location%20desc&limit=1' \
-u superuser:superuser |
...
| title | Click to see the resulting JSON |
|---|
| Code Pro | ||
|---|---|---|
| ||
[
{
"@name": "The-Trans-Siberian-Railway",
"@path": "/magnolia-travels/The-Trans-Siberian-Railway",
"name": "The Trans-Siberian Railway",
"description": "A fascinating tour through Russia.",
"location": "Vladivostok, Russia",
"tourTypes": [
"e007e401-1bf8-4658-8293-b9c743784264"
],
"author": "Magnolia Travels",
"body_de": "<p>Gehen Sie auf eine epische Zugfahrt, die über ein Drittel der Welt verläuft, in Vladivostok, Russlands größter Hafenstadt, beginnt und im majestätischen Moskau endet. Die legendäre Transsibirische Eisenbahn verläuft von der mongolischen Steppe zu den fernen Ufern des Baikalsees und zu den schneebedeckten Bergen des Urals; sie gibt Ihnen einen seltenen Einblick in die so unterschiedlichen Landschaften Russlands. Im Komfort Ihres Luxus-Zuges erfahren Sie mehr über die russische Geschichte von den Mongolen bis zu den Zaren und Kommunisten.</p> ",
"body": "<p>Set out on an epic train journey that goes across one-third of the world, starting in Vladivostok, Russia’s biggest port city, and ending in majestic Moscow. The legendary Trans-Siberian Railway goes from the Mongolian steppe to Lake Baikal’s remote shores to the snow-capped Ural Mountains, giving you a rare view on Russia’s vastly differing landscapes. You’ll be able to find out more about Russian history, from the Mongols right through to Tsars and communists, all from the comfort of your luxury train.</p> ",
"description_de": "Faszinierende Reise durch Russland",
"destination": [
"6cc50e28-fb0e-4e49-b3b6-728690a2e861"
],
"duration": "21",
"name_de": "Die Trans-Sibirische Eisenbahn",
"image": "jcr:5d3a5a2c-dec2-4ac6-915f-0a487aaecf7f",
"@nodes": []
}
] |
...
| 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.
Basic configuration
| 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.
Configuring reference resolving
...
.
Overview
Content Tools