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 the delivery endpoint for obtaining JCR data as JSON. The endpoint provides two resources that can be called with HTTP GET . The endpoint has to be configured, which enables its customization.
Currently we only support a single delivery endpoint configuration. Please note that a preconfigured endpoint is delivered by default in bundles that contain the demo.
We plan to support multiple endpoints soon. Keep an eye on MGNLREST-152 - Getting issue details... STATUS to see how development is coming along!
readNode
Returns one node by a given path, including its properties and child nodes down to a certain depth.
GET /delivery/{endpointPrefix}/v1/{path}
Parameter | Description | Data type |
| required The name of an endpoint prefix as configured. Also can be a real workspace name. |
|
| required The path relative to the |
|
Get the node of the first component in the main
area of the /travel/about
page.
curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/delivery/website/v1/travel/about/main/00' \ -u superuser:superuser
queryNodes
Returns a list of nodes matching a query composed of the given query parameters. You also can apply filters to the query.
GET /delivery/{endpointPrefix}/v1?param1=value1¶m2=value2&...
Use any of the optional query parameters or none.
Parameter | Description | Parameter type | Data type |
| required The name of an endpoint prefix as configured. Also can be a real workspace name. |
|
|
| optional A search phrase (full-text search) |
|
|
| optional The properties by which to order the nodes. Example: Note that special characters such as a space ( |
|
|
offset | optional, default is The start position in a result list (for pagination) | query | Integer |
| optional, default is as set in configuration The number of nodes displayed in a pagequery. Used together with |
|
|
<filter> | 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 |
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.
The filter parameter has the following format: property[operator]=value
Example filter used in a URL:
https://example.com/.rest/delivery/pages/v1?title[like]=tour
eq
(means =
)ne
(means <>
)lt
(means <
)gt
(means >
)lte
(means <=
)gte
(means >=
)like
(means LIKE
) %
(percentage, URL encoded as %25
) stand for zero or more additional characters._
(underscore) stands for any one character.in
(means IN
)not-in
(means NOT IN
)Filter for a node property. The property value must be an exact match.
author=Magnolia%20Travels
@name
property filterFilter by a node name.
@name=travel
@ancestor
filterFind nodes for whom 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
If no operator is provided, eq
is used by default.
The value
in the filter parameter is treated as String
.
Use brackets to pass an operator, for example [eq]
, [ne]
, [lt]
, and so on.
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
price[in]=100~200
is interpreted as price >= 100 AND price <= 200
.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
Find webpages in the Travel Demo which were last modified before or on June 3, 2015:
curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/delivery/website/v1?mgnl:lastModified\[lte\]=2015-06-03' \ -u superuser:superuser
\
) for the command to work correctly in bash.Find webpages whose title is either Story or Stories. This can be done in two ways:
curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/delivery/website/v1?title=Story|Stories' \ -u superuser:superuser
curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/delivery/website/v1?title\[like\]=Stor%25' \ -u superuser:superuser
\
) for the command to work correctly in bash.)Find nodes in the tours
workspace which contain the keyword vietnam. Return the results in the descending order by the location
property and restrict the limit to one:
curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/delivery/tours/v1?q=vietnam&orderBy=location%20desc&limit=1' \ -u superuser:superuser
Find a tour whose description
is Get photobombed by a Sea Turtle:
curl -X GET \ 'http://localhost:8080/magnoliaAuthor/.rest/delivery/tours/v1?description=Get%20photobombed%20by%20a%20Sea%20Turtle' \ -u superuser:superuser
In the website
workspace, find all nodes for whom /travel/about/careers is the ancestor:
curl -X GET \ 'http://localhost:8080/magnoliaAuthor/.rest/delivery/website/v1?@ancestor=/travel/about/careers' \ -u superuser:superuser
The delivery endpoint requires a configuration, which can be done in YAML file or via JCR, otherwise, it cannot deliver content. Version 2.0 of the Add the configuration to the Properties: required Must be optional default= Must be required The map defining at least one or more endpoint prefixes. 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 optional The name of the JCR workspace to deliver content from. Must be set if the parent optional , default is A list of allowed node types for depth-0 nodes. optional default is A list of allowed node types for child nodes. optional, default is The depth of child nodes to display in the result. optional, default is Specifies whether the result should show system properties. optional The root path of this endpoint. The path information when requesting the endpoint is added to this path. optional, default is If set to optional, default is The number of nodes (of level 0) in the result. Used only in the The property can be overridden when calling A node may contain references to other nodes. With the Properties of An arbitrary name for a ReferenceDefinition. The reference resolver definition for this reference. Its definition class is ReferenceResolverDefinition. A class implementing ReferenceResolverDefinition. Current implementations: UuidReferenceResolver.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.restEndpoints
folder in a light module or within src/main/resources/<module-name>/restEndpoints
in a Magnolia Maven module.Basic configuration
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
class
info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpointDefinition
or a subclass.implementationClass
info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpoint
info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpoint
or a subclass.params
<endpointPrefix>
workspace
.workspace
<endpointPrefix>
is not a real workspace name.nodeTypes
mgnl:content
mgnl:folder
is ignored deliberately.childNodeTypes
mgnl:contentNode
depth
0
includeSystemProperties
true
rootPath
bypassWorkspaceAcls
false
true
, JCR security is bypassed. Use this with care and for development reasons only!limit
10
queryNodes
method.queryNodes
with a request parameter.Reference resolving configuration
references
property, you can extend the configuration to force it to resolve the referenced nodes per workspace.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
references
:references
A map which contains at least one reference definition. <reference-name>
propertyName
The name of the JCR property which stores the reference. It can be a multi-value property. referenceResolver
implementationClass
targetWorkspace
The name of the workspace where the referenced node resides.