Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
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
Mgnl get |
---|
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/{endpointPrefix}/v1/{path}
...
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
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 |
...
title | Click to see the resulting JSON |
---|
The result is based on the simple configuration.
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": []
} |
queryNodes
Returns a list of nodes matching a query composed of the given query parameters.
Mgnl get |
---|
/delivery/{endpointPrefix}/v1?param1=value1¶m2=value2&...
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
...
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*
...
query
...
String
...
The start position in a result list (for pagination)
...
limit
...
optional, default: as set in YAML configuration
The number of nodes displayed in a page query. Used together with offset
for pagination.
...
query
...
Integer
*) 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
...
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/tours/v1?q=vietnam&orderBy=location%20desc&limit=1' \
-u superuser:superuser |
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
The result is based on the simple configuration.
Note that the response above was created with a basic configuration and without reference resolving. See lines 9-12 |
...
MultiExcerptName | configuration |
---|
The delivery endpoint requires a YAML configuration or 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 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 | ||||
---|---|---|---|---|
| ||||
class: info.magnolia.rest.delivery.jcr.v1.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
rootPath: /travel-demo |
Properties:
...
required
Must be info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpointDefinition
or a subclass.
...
required
Must be info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpoint
or a subclass.
...
required
The map defining at least one or more workspaces.
...
<endpointPrefix>
required
Defines an endpoint prefix where requests will be routed and handled according to the associated workspace parameters below.
...
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=mgnl:content
A list of allowed node types for depth-0 nodes. mgnl:folder
is ignored deliberately.
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. |
...
childNodeTypes
...
optional default=mgnl:contentNode
A list of allowed node types for child nodes.
...
depth
...
The depth of subnodes 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 |
...
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.
...
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 | ||||
---|---|---|---|---|
| ||||
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: /
tours:
rootPath: /
includeSystemProperties: false |
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 to see a response with resolved references |
---|
...
language | js |
---|
...