Page History

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

Mgnl get

. 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

Mgnl get

<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

language	js

{
  "@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&rsquo;ll always remember.</p> ",
  "text_de": "<p>Wir sind eine unabh&auml;ngige Reiseagentur mit Rundumservice.</p>\n<p>Wir bieten einzigartige Reisen f&uuml;r jeden Kontinent der Erde an. Lassen Sie sich inspirieren und buchen Sie Ihre Reise bei uns, um Erfahrungen zu machen, die Ihnen f&uuml;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

Mgnl get

<magnolia-base-path>/.rest/delivery/{endpointPrefix}/v1?param1=value1&param2=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

optional, default is 0

The start position in a result list (for pagination)

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

Anchor

	anc-orderBy
	anc-orderBy

orderBy

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

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
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

...

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)

]=tour

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.

Code Block
@name=travel

@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

Ranges are inclusive: price[in]=100~200 is interpreted as price >= 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-dd
  Code Block
  2018-01-01
- Datetime: yyyy-MM-dd'T'HH:mm:ss.SSSXXX
  Code Block
  2018-01-11T10:26:47.438+07:00
If a filter can take multiple possible values which must match, use | (OR):
Code Block
@name=travel|about

...

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.

Anchor
basic-config
basic-config
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 configuration

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

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.

...

Page tree

Versions Compared

Old Version 12

New Version Current

Key

Methods

Read node

Request URL

Parameters

Example

Query nodes

Request URL

Parameters

Anchor
queryNodes-filter
queryNodes-filter
Filters

Filter format

Supported filter operators

Supported filter operators

Filter types

Usage notes

Anchor
basic-config
basic-config
Basic configuration

Anchor
anc-reference-resolving-configuration
anc-reference-resolving-configuration
Reference resolving configuration

Page tree

Page History

Versions Compared

Old Version 12

New Version Current

Key

Methods

Read node

Request URL

Parameters

Example

Query nodes

Request URL

Parameters

AnchorqueryNodes-filterqueryNodes-filterFilters

Filter format

Supported filter operators

Supported filter operators

Filter types

Usage notes

Anchorbasic-configbasic-configBasic configuration

Anchoranc-reference-resolving-configurationanc-reference-resolving-configurationReference resolving configuration

Anchor
queryNodes-filter
queryNodes-filter
Filters

Anchor
basic-config
basic-config
Basic configuration

Anchor
anc-reference-resolving-configuration
anc-reference-resolving-configuration
Reference resolving configuration