Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
This page describes the delivery endpoint version 2 for obtaining JCR data as JSON.
This REST resource is highly customizable. You can define multiple endpoint configurations to serve different needs. Each configured endpoint is accessed through a distinct
endpointPath
and provides three methods. The methods, called with HTTP GET, allow you read a node (and its subnodes) by a given path, get children of a node and query nodes.
To help you configure and try out the delivery scenarios mentioned on this page, we:
- Use
deliveryas part of the endpoint path. Our webapps come with a pre-configured user role calledrest-anonymous, which allows anonymous users to access the/.rest/delivery/*path. - Set the
bypassWorkspaceAclsproperty totruein all endpoint configurations. Otherwise, you would have to use the Security app and configure an access control list for the anonymous user to be able to access the nodes inside the various workspaces the delivery scenarios utilize.
Methods
Please note that sending a request to a URI that ends with just the endpointPath invokes the Query nodes method. Attaching or not attaching the slash to the endpointPath has no effect in this:
GET <magnolia-base-path>/.rest/endpointPath/
GET <magnolia-base-path>/.rest/endpointPath
Read node
This method returns one node by a given path, including its properties and child nodes down to a certain depth. Child nodes are returned in the natural order.
Request URL
GET <magnolia-base-path>/.rest/endpointPath/{path}
Parameters
Parameter | Description | Data type |
|---|---|---|
| required The path relative to the |
|
Example
Get all component nodes of the main area of the /travel/about page.
curl 'http://localhost:8080/magnoliaAuthor/.rest/delivery/ep/travel/about/main'
Get children
(
Magnolia 5.6.6+) This method is a special variant of the read node method. It uses the @nodes handle to retrieve child nodes of a path in a configured endpoint. To use the handle, append it to the path of a URI:
Request URL
GET <magnolia-base-path>/.rest/endpointPath/{path}@nodes
The items in the response are returned in their natural (unsorted) order, see also the orderBy request parameter.
Examples
Get child nodes in the root of the
ependpoint:curl "https://localhost:8080/magnoliaAuthor/.rest/delivery/ep/@nodes"
Get child nodes in the root of the
/travelpage:curl "https://localhost:8080/magnoliaAuthor/.rest/delivery/ep/travel/@nodes"
Query nodes
Returns a list of nodes matching a query composed of the query parameters provided. You can also apply filters to the query.
Request URL
GET <magnolia-base-path>/.rest/endpointPath?param1=value1¶m2=value2&...
Use any of the optional query parameters or none.
Parameters
Parameter | Description | Parameter type | Data type |
|---|---|---|---|
| optional A search phrase (full-text search). |
|
|
| optional The properties by which to order the nodes. The result may be returned either in the ascending ( Example: Note that special characters such as a space ( Example:
The results are returned unsorted if no |
|
|
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 page query. Use 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, and so on. You can combine filters with an |
Examples follow after the Filters section.
Filters
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.
Filter format
The filter parameter has the following format: property[operator]=value
Example filter used in a URL:
http://localhost:8080/magnoliaAuthor/.rest/my-endpoint?description[like]=%25demonstration%25
In some REST clients, you may need to URL-encode also the key in the filter parameter. The RFC standard called Uniform Resource Identifier (URI): Generic Syntax (https://tools.ietf.org/html/rfc3986#section-2.2) maintains that
If data for a URI component would conflict with a reserved character's purpose as a delimiter, then the conflicting data must be percent-encoded before the URI is formed.
For example:
http://localhost:8080/magnoliaAuthor/.rest/my-endpoint?description
%5B
like
%5D
=%25demonstration%25
Supported filter operators
| Operator | Meaning |
|---|---|
eq | = |
ne | <> |
gt | > |
lt | < |
lte | <= |
gte | >= |
in | IN |
not-in | NOT IN |
Can be used with:
|
Can be used with:
|
null |
The value can be either The operator can be used with any property. |
Filter types
Property filter
Filter for a node property. The property value must be an exact match.
author=Magnolia%20Travels
@name property filter
Filter by a node name.
@name=travel
@jcr:uuid filter
Filter by the JCR node ID (uuid). The property value must be an exact match.
@jcr:uuid=<id>
@ancestor filter
Find nodes for which 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
Usage notes
If no operator is provided,
eqis used by default.The
valuein the filter parameter is treated asString.Use brackets to pass an operator, for example
[eq],[ne],[lt], and so on.For
inandnot-in, a range symbol~(the tilde) should be provided, for example:http://localhost:8080/magnoliaAuthor/.rest/my-endpoint?mgnl:created[in]=2015-12-01~2015-12-31
- Ranges are inclusive:
price[in]=100~200is interpreted asprice >= 100 AND price <= 200. - For filtering by date and time, only two ISO 8601-based formats are accepted. The patterns shown are in JAVA notation (java.text.SimpleDateFormat):
Date:
yyyy-MM-dd2018-01-01
Datetime:
yyyy-MM-dd'T'HH:mm:ss.SSSXXX2018-01-11T10:26:47.438+07:00
If a filter can take multiple possible values which must match, use
|(OR):@name=travel|about
Examples
We assume you are familiar with
cURL. Note that cURL requires URL encoding.See tools to test REST requests for other possibilities.
Find webpages in the Travel Demo which were last modified before or on June 3, 2015:
curl 'http://localhost:8080/magnoliaAuthor/.rest/delivery/ep/?mgnl:lastModified[lte]=2015-06-12' --globoff
By using the option --globoffyou can specify URLs that contain the letters {}[] without having them being interpreted by cURL itself.
Find webpages with the word "Customer" in the title.
Usecurl -g -G "http://localhost:8080/magnoliaAuthor/.rest/delivery/ep" --data-urlencode "title[like]=%Customer%"
--data-urlencodeand-g -Gto encode the request parameter values, if required.
In the
websiteworkspace, find all nodes for which/travel/about/careersis the ancestor:curl 'http://localhost:8080/magnoliaAuthor/.rest/delivery/ep/?@ancestor=/travel/about/careers'
Find nodes in the
toursworkspace that contain the keyword "beach". Return the results in descending order based on thelocationproperty and restrict the number of results to three:curl 'http://localhost:8080/magnoliaAuthor/.rest/delivery/ep/?q=beach&orderBy=location%20desc&limit=3'
Find a tour with the word "Japan" in its
description. Return only the variant in the German language:curl -g -G 'http://localhost:8080/magnoliaAuthor/.rest/delivery/ep?lang=de-DE' --data-urlencode "description[like]=%Japan%"
Note that we use
--data-urlencodeto encode one of the request parameters, whereas the one that does not require encoding is added to the URL directly.
Filtering on specific languages
To get REST results for a specific language you may have to specify a language suffix in the search query. Let's consider an example based on the default installation of the Travel Demo bundle, where the content in the Tours app (stored in the tours workspace) is available both in English and in German and English is the default language for the site.
Searching for Erleben in the content of the body properties of the workspace by sending a query such as
http://localhost:8080/magnoliaAuthor/.rest/delivery/ep/?body[like]=%Erleben%
yields no results since Erleben is present only in the German content variant:
In the search query you need specify the language by appending - in this case - the _de suffix to the body property and re-send
http://localhost:8080/magnoliaAuthor/.rest/delivery/ep/?body_de[like]=%Erleben%
instead. Only this will return a result (click the link to expand to see the actual result):
This result is returned for the endpoint called ep with the following configuration:
class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition workspace: tours bypassWorkspaceAcls: true includeSystemProperties: false
Notice that in spite of searching within body_de the content in the output is in English. This is caused by sending the en value in the Content-Language header sent along with the query. To obtain a response with content in German, you would need to append &lang=de to the query.
If you try to find the English equivalent (Experience), you must not specify the _en suffix since English is the site's default language. Using this suffix in the query returns an empty result set:
{"results":[]}
There's no property body_en present in the tours workspace.
Alternatively, try searching with a more general search query such as
http://localhost:8080/magnoliaAuthor/.rest/delivery/ep/?q=Erleben
which will also return a response where Erleben appears in the JCR (endpoint configuration is same as the one above):
For i18n features to work correctly, check that the fallback site has locales configured or extends a site definition with desired locales.
Configuration
You can define multiple endpoints in this version of the delivery endpoint. The endpointPath property is used to access the different configured endpoints.
Example
restEndpoints/my-endpoint.yaml
class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition workspace: website bypassWorkspaceAcls: true limit: 25 depth: 2 includeSystemProperties: false nodeTypes: - mgnl:page childNodeTypes: - mgnl:area - mgnl:component #references
| Node name | Value |
|---|---|
restEndpoints | |
my-endpoint | |
class | info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition |
workspace | website |
bypassWorkspaceAcls | true |
limit | 25 |
depth | 2 |
includeSystemProperties | false |
nodeTypes | |
0 | mgnl:page |
childNodeTypes | |
0 | mgnl:area |
1 | mgnl:component |
Properties
class | required Must be |
endpointPath | optional If the property is not set, the If you set the property manually, it should not contain special characters to fit into a proper URL. |
workspace | required The name of the JCR workspace to deliver content from. |
rootPath | optional, default is The root path of this endpoint. The path information is added to this path when requesting the endpoint. |
nodeTypes | optional , default is A list of allowed node types for depth-0 nodes. |
childNodeTypes | optional , default is A list of allowed node types for child nodes. |
strict | optional , default is Defines whether to include only the exact node type and ignore the sub types. If true then it is applied to both the |
depth
| optional, default is Specifies how deep the node tree will be traversed. The default value ( |
includeSystemProperties | optional, default is Specifies whether the result should show system properties. |
limit | optional, default is The number of nodes (of level 0) in the result. Used only in the The property can be overridden when calling |
bypassWorkspaceAcls | optional, default is If set to |
references | optional This property allows you to resolve referenced nodes. For image variations to be resolved correctly, make sure that the fallback site has theme variations configured or extends a site definition with desired variations. |
The endpointPath property
The endpointPath is used to access a configured delivery endpoint.
<magnolia-base-path>/.rest/endpointPath/{path} <magnolia-base-path>/.rest/endpointPath?query-parameters
The value of the endpointPath can be set as a property in the configuration. If you do not set the property manually, the system evaluates it automatically.
If you do not set the property in the configuration:
- The value set by the system is the path of the configuration relative to the
restEndpointsfolder. - You can add
_v$numberto the YAML file name or JCR node name that defines the endpoint in order to add a version to theendpointPathevaluated by the system .
Examples:
| YAML file location | endpointPath |
|---|---|
| my-module/restEndpoints/my-endpoint.yaml | my-endpoint |
| my-module/restEndpoints/delivery/another-endpoint.yaml | delivery/another-endpoint |
| my-module/restEndpoints/delivery/another-endpoint_v3.yaml | delivery/another-endpoint/v3 |
JCR node path inconfiguration workspace | endpointPath |
| /modules/my-custom-module/restEndpoints/super-endpoint | super-endpoint |
| /modules/my-custom-module/restEndpoints/delivery/mega-endpoint | delivery/mega-endpoint |
| /modules/my-custom-module/restEndpoints/delivery/mega-endpoint_v2 | delivery/mega-endpoint/v2 |
Location of the endpoint definitions
Magnolia REST endpoint definitions are true Magnolia Resources. You can create them in a light module, in a Magnolia Maven module or in the JCR configuration workspace.
In a light module
Add configurations to the folder restEndpoints or to subfolders.
my-light-module/
└── restEndpoints
├── delivery
│ └── another-endpoint.yaml
└── my-endpoint.yaml
In a Magnolia Maven module
Add configurations to the folder resources/my-maven-module/restEndpoints or to subfolders.
my-maven-module/
└── src
└── main
└── resources
└── my-maven-module
└── restEndpoints
├── delivery
│ └── johns-endpoint.yaml
└── larrys-endpoint.yaml
In the JCR configuration workspace
Add configurations to the folder /modules/my-custom-module/restEndpoints or to subfolders.
| Node name |
|---|
modules |
my-custom-module |
restEndpoints |
super-endpoint |
delivery |
mega-endpoint |
Overview
Content Tools
3 Comments
Ravindra Kumar Verma
Christoph Meier Martin Drápela I have created a content app using the groovy script then configured delivery endpoint v2 as mentioned in above document. but while accessing it using Rest endpoint gives me empty result array always with 200 Ok response..
but when I try to configure the same delivery v2 endpoint in pre-installed Contact app it works in return all the node.
I don't know what configuration I am missing, Please suggest. attached my JCR tree structure.
https://ibb.co/zhfChFB
Christoph Meier
Ravindra Kumar Verma
When addressing your questions to one of the Magnolia google groups, you have a bigger audience and more people which may help you.
Considering your "JCR tree".
Rather define your stuff in YAML, which is an easy format to exchange between people.
If you insist in JCR, export the JCR and provide the bootstrap.
Ravindra Kumar Verma
Thanks, Christoph Meier it helps a lot.
I got the issue, if I generate the content app from groovy then it will return the empty result but if I generate it maven project and deploy as a jar , it will return the correct result with delivery v2 API.
any specific reason?