This page describes the delivery
endpoint version 1 for obtaining JCR data as JSON. The endpoint provides two resources methods that can be called with HTTP
. You can
only create
one configuration, which is required in order a single configuration that is required to use it.
Note |
---|
The version Version 1 of the delivery endpoint is deprecated. We recommend using version 2 instead. |
Table of Contents |
---|
maxLevel | 4 |
---|
minLevel | 2 |
---|
exclude | Parameters |
---|
|
Methods
Read node
Returns one node by a given path, including its properties and child nodes down to a certain depth.
Request URL
<magnolia-base-path>/.rest/delivery/{endpointPrefix}/v1/{path}
Parameters
Advanced Tables - Table Plus |
---|
highlightColor | @default |
---|
multiple | false |
---|
enableHeadingAttributes | false |
---|
enableSorting | false |
---|
enableHighlighting | false |
---|
|
Parameter | Description | Data type |
---|
endpointPrefix
| required The name of an endpoint prefix as configured. Also can May also be a real workspace name. | String
| path
| required The path relative to the rootPath defined in the configuration. | String
| |
Example
Get the node of the first component in the main
area of the /travel/about
page.
...
Expand |
---|
title | Click to see the resulting JSON |
---|
|
Code Pro |
---|
| {
"@name": "00",
"@path": "/travel/about/main/00",
"@id": "01db6fc1-78af-4284-adf0-8c997309df6a",
"@nodeType": "mgnl:component",
"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> ",
"headline_de": "Über Magnolia Travels",
"imagePosition": "below",
"headlineLevel": "small",
"headline": "About Magnolia Travels",
"@nodes": []
} |
The This result is based on the basic configuration. |
Query nodes
Returns a list of nodes matching a query composed of the given query parameters provided. You You can also can apply filters to the query.
Request URL
<magnolia-base-path>/.rest/delivery/{endpointPrefix}/v1?param1=value1¶m2=value2&...
Use any of the optional query parameters or none.
Parameters
Advanced Tables - Table Plus |
---|
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. Also can May also be a real workspace name. | path
| String
| q
| optional A search phrase (full-text search). | query
| String
| | optional The properties by which to order the nodes. Example: mgnl:lastModified desc,title asc 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 must encode it manually or with an additional tool. Example: orderBy=title%20asc | query
| String
| offset | optional, default is 0 The start position in a result list (for pagination) query | Integer | limit
| optional, default is as set in configuration The number of nodes displayed in a pagequery. Used together with offset for pagination. | query
| Integer
| Please note that until Magnolia 5.6.5 the results provided by the endpoint were sorted alphabetically on node names (same as with the ORDER BY LOWER(NAME(t)) statement in the JCR-SQL2 query) even though no orderBy parameter was set in the request URL. Since Magnolia 5.6.5 the results are returned unsorted if no orderBy parameter is set. This however does not mean "in natural order" since many other aspects may be involved, such as the setting of the respectDocumentOrder property or index consistency. For more information, see Apache Jackrabbit Search and Rebuilding the Index. | query
| String
| offset | optional, default is 0 The start position in a result list (for pagination). | query | Integer | limit
| optional, default is as set in configuration The number of nodes displayed in a page query. Use together with offset for pagination. | query
| Integer
| <filter> | optional There | <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 and so on. You can combine filters with an AND operator. See filter options. |
|
| |
Anchor |
---|
| queryNodes-filter |
---|
| queryNodes-filter |
---|
|
FiltersqueryNodes
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
...
Code Block |
---|
https://example.com/.rest/delivery/pages/v1?title[like]=tour |
Supported filter operators
eq
(means =
)ne
(means <>
)lt
(means <
)gt
(means >
)lte
(means <=
)gte
(means >=
)like
(means LIKE
)
Two wildcard characters can be used in the search pattern:%
(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
)
Supported filter operators
Include Page |
---|
| _filter operators |
---|
| _filter operators |
---|
|
Filter types
Property filter
Filter for a node property. The property value must be an exact match.
Code Block |
---|
author=Magnolia%20Travels |
@name
property filter
Filter by a node name.
@ancestor
filter
Find nodes for whom which the path provided is the ancestor. The path must be absolute in the given workspace of the given workspace prefix.
Code Block |
---|
@ancestor=/travel/about/careers/marketing-associate |
Usage notes
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:
Code Block |
---|
https://example.com/.rest/delivery/pages/v1?mgnl:created[in]=2018-01-01~2018-02-01 |
...
Multiexcerpt |
---|
MultiExcerptName | configuration |
---|
|
The delivery endpoint requires a configuration, otherwise, or it cannot deliver content. Version 1 of the delivery endpoint can only have only one configuration. You can decorate the definition. Add the configuration to the restEndpoints folder in a light module, within src/main/resources/<module-name>/restEndpoints in a Magnolia Maven module or as JCR in the configuration workspace. Basic configuration Code Pro |
---|
language | yaml |
---|
title | my-lightmodule/restEndpoints /my-endpoint.yaml |
---|
| 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 |
Properties: class | required Must be info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpointDefinition or a subclass. | implementationClass | optional, default =is info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpoint Must be info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpoint or a subclass. | params | required The map defining at least one or more endpoint prefixes. | <endpointPrefix>
| required Defines an endpoint prefix where requests will be are routed and handled according to the associated workspace parameters parameter below. The value can be an arbitrary name (no special characters !allowed) - , or it can be a real workspace name. If it is not a real workspace name, you must provide the sub property workspace . | 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 is mgnl:content A list of allowed node types for depth-0 nodes. mgnl:folder is ignored deliberately. | childNodeTypes
| optional, default is mgnl:contentNode
A list of allowed node types for child nodes. | depth
| optional, default is 0 The depth of child nodes to display in the result. | includeSystemProperties
| optional,default is true 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 true , JCR security is bypassed. Use this property with care and for development reasons purposes only!. |
| 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. | Anchor |
---|
| anc-reference-resolving-configuration |
---|
| anc-reference-resolving-configuration |
---|
| Reference resolving configurationA 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 |
---|
language | yaml |
---|
linenumbers | true |
---|
| 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 |
Properties of references : references | A map which contains at least one reference definition. | <reference-name>
| An arbitrary name for a Javadoc resource link |
---|
className | info.magnolia.rest.reference.ReferenceDefinition |
---|
renderType | asynchronous |
---|
|
. | propertyName
| The name of the JCR property which stores the reference. It can be a multi-value property. | referenceResolver
| The reference resolver definition for this reference. Its definition class is Javadoc resource link |
---|
className | info.magnolia.rest.reference.ReferenceResolverDefinition |
---|
renderType | asynchronous |
---|
|
. | implementationClass
| A class implementing Javadoc resource link |
---|
className | info.magnolia.rest.reference.ReferenceResolverDefinition |
---|
renderType | asynchronous |
---|
|
. Current implementations: Javadoc resource link |
---|
className | info.magnolia.rest.reference.jcr.UuidReferenceResolver |
---|
renderType | asynchronous |
---|
|
. | targetWorkspace
| The name of the workspace where the referenced node resides. | |
...