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 1 for obtaining JCR data as JSON. The endpoint provides two methods that can be called with HTTP GET. You can only create a single configuration that is required to use it.
Version 1 of the delivery endpoint is deprecated. We recommend using version 2 instead.
Methods
Read node
Returns one node by a given path, including its properties and child nodes down to a certain depth.
Request URL
GET <magnolia-base-path>/.rest/delivery/{endpointPrefix}/v1/{path}
Parameters
Parameter | Description | Data type |
|---|---|---|
| required The name of an endpoint prefix as configured. May also be a real workspace name. |
|
| required The path relative to the |
|
Example
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
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/delivery/{endpointPrefix}/v1?param1=value1¶m2=value2&...
Use any of the optional query parameters or none.
Parameters
Parameter | Description | Parameter type | Data type |
|---|---|---|---|
| required The name of an endpoint prefix as configured. May also 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 ( Example:
Since Magnolia 5.6.5 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 |
Please note that until Magnolia 5.6.5 the results provided by the endpoint were sorted alphabetically on node names (same as with the 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:
https://example.com/.rest/delivery/pages/v1?title[like]=tour
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
@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:https://example.com/.rest/delivery/pages/v1?mgnl:created[in]=2018-01-01~2018-02-01
- 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
Find webpages in the Travel Demo which were last modified before or on June 3, 2015:
The brackets have been escaped with the backslash character (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 with either "Customer Experience Agent" or "Customer Experience Supervisor" as the title. This can be done in two ways:
curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/delivery/website/v1?title=Customer%20Experience%20Agent|Customer%20Experience%20Supervisor' \ -u superuser:superuser
The brackets have been escaped with the backslash character (curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/delivery/website/v1?title\[like\]=Customer%20Experience%20%25' \ -u superuser:superuser
\) for the command to work correctly in bash.
In the
websiteworkspace, find all nodes for which/travel/about/careersis the ancestor:curl -X GET \ 'http://localhost:8080/magnoliaAuthor/.rest/delivery/website/v1?@ancestor=/travel/about/careers' \ -u superuser:superuser
Find nodes in the
toursworkspace that contain the keyword "beach". Return the results in the descending order based on thelocationproperty and restrict the number of results to three:curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/delivery/trips/v1?q=beach&orderBy=location%20desc&limit=3' \ -u superuser:superuser
Find a tour with the
description"Get photobombed by a Sea Turtle":curl -X GET \ 'http://localhost:8080/magnoliaAuthor/.rest/delivery/trips/v1?description=Get%20photobombed%20by%20a%20Sea%20Turtle' \ -u superuser:superuser
Configuration
The delivery endpoint requires a configuration, or it cannot deliver content. Version 1 of the delivery endpoint can only have one configuration. You can decorate the definition. Add the configuration to the Properties: required Must be optional, default is Must be required The map defining at least one or more endpoint prefixes. required Defines an endpoint prefix where requests are routed and handled according to the associated workspace 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 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.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
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
classinfo.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpointDefinition or a subclass.implementationClassinfo.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.nodeTypesmgnl:content mgnl:folder is ignored deliberately.childNodeTypesmgnl:contentNode depth0 includeSystemPropertiestrue rootPathbypassWorkspaceAclsfalse true, JCR security is bypassed. Use this property with care and for development purposes only.limit10 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:referencesA map which contains at least one reference definition. <reference-name>propertyNameThe name of the JCR property which stores the reference. It can be a multi-value property. referenceResolverimplementationClasstargetWorkspaceThe name of the workspace where the referenced node resides.
Overview
Content Tools