Magnolia 6.1 reached end of life on March 31, 2021. This branch is no longer supported, see End-of-life policy.
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:
delivery
as part of the endpoint path. Our webapps come with a pre-configured user role called rest-anonymous
, which allows anonymous users to access the /.rest/delivery/*
path.bypassWorkspaceAcls
property to true
in 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.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
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.
GET <magnolia-base-path>/.rest/endpointPath/{path}
Parameter | Description | Data type |
---|---|---|
| required The path relative to the |
|
Get all component nodes of the main
area of the /travel/about
page.
curl 'http://localhost:8080/magnoliaAuthor/.rest/delivery/ep/travel/about/main'
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:
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.
Get child nodes in the root of the ep
endpoint:
curl "http://localhost:8080/magnoliaAuthor/.rest/delivery/ep/@nodes"
Get child nodes in the root of the /travel
page:
curl "http://localhost:8080/magnoliaAuthor/.rest/delivery/ep/travel/@nodes"
Returns a list of nodes matching a query composed of the query parameters provided. You can also apply filters to the query.
GET <magnolia-base-path>/.rest/endpointPath?param1=value1¶m2=value2&...
Use any of the optional query parameters or none.
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.
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:
http://localhost:8080/magnoliaAuthor/.rest/my-endpoint?description[like]=%25demonstration%25
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. |
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
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:
http://localhost:8080/magnoliaAuthor/.rest/my-endpoint?mgnl:created[in]=2015-12-01~2015-12-31
price[in]=100~200
is interpreted as price >= 100 AND price <= 200
.java.text.SimpleDateFormat
):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
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 12, 2015:
curl 'http://localhost:8080/magnoliaAuthor/.rest/delivery/ep/?mgnl:lastModified[lte]=2015-06-12' --globoff
--globoff
you can specify URLs that contain the letters {}[] without having them being interpreted by cURL itself.Find webpages with the word "Customer" in the title.
curl -g -G "http://localhost:8080/magnoliaAuthor/.rest/delivery/ep" --data-urlencode "title[like]=%Customer%"
--data-urlencode
and -g -G
to encode the request parameter values, if required.In the website
workspace, find all nodes for which /travel/about/careers
is the ancestor:
curl 'http://localhost:8080/magnoliaAuthor/.rest/delivery/ep/?@ancestor=/travel/about/careers'
Find nodes in the tours
workspace that contain the keyword "beach". Return the results in descending order based on the location
property and restrict the number of results to two:
curl 'http://localhost:8080/magnoliaAuthor/.rest/delivery/ep/?q=beach&orderBy=location%20desc&limit=2'
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-urlencode
to encode one of the request parameters, whereas the one that does not require encoding is added to the URL directly.
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
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.
You can define multiple endpoints in this version of the delivery endpoint. The endpointPath
property is used to access the different configured endpoints.
class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition workspace: website bypassWorkspaceAcls: true limit: 25 depth: 2 includeSystemProperties: true 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 | true |
nodeTypes | |
0 | mgnl:page |
childNodeTypes | |
0 | mgnl:area |
1 | mgnl:component |
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 when requesting the endpoint is added to this path. |
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 The depth of child nodes to include in each returned item. This does not restrict which nodes will be returned from a query. It just determines the number of child nodes in each returned item. |
includeSystemProperties | optional, default is Specifies whether the result should show system properties. |
systemProperties | optional (Magnolia 6.1.3+) List of system properties that should be returned in the response. You can specify the properties using a full property name, as seen on line 4 below, or using a wildcard character (line 5, to request for example <light-module>/restEndpoints/ep.yaml class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition workspace: tours systemProperties: - mgnl:tags - "*By" The |
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. |
referenceDepth | optional, default is Defines on how many levels the references should be considered and returned in a response if found. Setting |
referenceRepeat | optional, default is The default setting eliminates resolving self-references into fully expanded nodes and thus creating reference cycles. If a self-reference is found, only the value of the |
endpointPath
propertyThe 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:
restEndpoints
folder.
_v$number
to the YAML file name or JCR node name that defines the endpoint in order to add a version to the
endpointPath
evaluated 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 |
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.
Best practice
Put the delivery endpoint configurations under the delivery
subfolder. This makes the endpoints easier to use because the default role rest-anonymous
is already configured to allow web access to the .rest/delivery/*
path.
Add configurations to the folder restEndpoints
or to subfolders.
my-light-module/ └── restEndpoints ├── delivery │ └── another-endpoint.yaml └── my-endpoint.yaml
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
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 |
4 Comments
Emilio Garza
Richard Gange - Are there any examples of how I could use delivery API to get component level content matching a certain Personalization Trait value? Looking to see if I could query by a trait value and get back a page's content with the matching component variations only and not all of the variations.
Richard Gange
Hey Emilio-
It's coming. I think this MGNLPN-474 - Getting issue details... STATUS is what you are asking for. Right now I have seen customers implementing this using Freemarker. Basically instead of rendering a page they render JSON after the personalized content has been filtered. If you can open a support ticket I can update you when this is ready. I would say probably later this year since it's part of the "SPA Editor Phase 2" epic.
HTH
Emilio Garza
Hey Richard Gange- Unrelated question to the above. On the subject of pagination with the delivery API, do you know of how I can get back from Magnolia the total number of results for a query if I've provided a limit / offset? This is helpful information to know how many pages of data there is when creating pagination without having to call the entire thing. I'm looking for in addition to the results a property that shares "total results" so I can divide it up into pages. This seems like a common thing in paginated APIs
Christopher Zimmermann
Hi Emilio, unfortunately that is not currently supported on the delivery endpoint. It would be great if you could suggest that improvement here: https://wiki.magnolia-cms.com/display/DEV/Suggestion+Box