Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
Page History
This page describes Use the delivery endpoint for obtaining API to obtain JCR data as JSON. The endpoint provides two resources that can be called with HTTP
| Mgnl get |
|---|
| Info | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
Currently we only support a single delivery endpoint configuration. Please note that a preconfigured endpoint is delivered by default in bundles that contain the demo. We plan to support multiple endpoints soon. Keep an eye on
|
| Table of Contents | ||||||
|---|---|---|---|---|---|---|
|
readNode
Returns one node by a given path, including its properties and child nodes down to a certain depth.
Request URL
| Mgnl get |
|---|
/delivery/{endpointPrefix}/v1/{path}Parameters
...
| 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 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.
| Code Pro |
|---|
curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/delivery/website/v1/travel/about/main/00' \
-u superuser:superuser |
| Expand | |||||
|---|---|---|---|---|---|
| |||||
The result is based on the basic configuration . |
queryNodes
Returns a list of nodes matching a query composed of the given query parameters. You also can apply filters to the query.
Request URL
| Mgnl get |
|---|
/delivery/{endpointPrefix}/v1?param1=value1¶m2=value2&... Use any of the optional query parameters or none.
Parameters
...
| 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 be a real workspace name.
...
path
...
String
...
q
...
optional
A search phrase (full-text search)
...
query
...
String
...
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 encode it manually or with an additional tool. Example: orderBy=title%20asc
...
query
...
String
...
The start position in a result list (for pagination)
...
limit
...
optional, default is as set in configuration
The number of nodes displayed in a pagequery. Used together with offset for pagination.
...
query
...
Integer
...
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 can combine filters with AND operator. See filter options.
...
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:
| 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(meansLIKE)in(meansIN)not-in(meansNOT IN)
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 for a node name.
| Code Block |
|---|
@name=travel |
@ancestor filter
Filter for ancestor nodes of a path provided. 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,
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:Code Block https://example.com/.rest/delivery/pages/v1?mgnl:created[in]=2018-01-01~2018-02-01
...
Date:
yyyy-MM-ddCode Block 2018-01-01Datetime:
yyyy-MM-dd'T'HH:mm:ss.SSSXXXCode 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 |
This REST resource is customizable and flexible to use.
Two versions of the delivery endpoint exist. Both versions can resolve references to nodes of other JCR workspaces. But only version 2 can deliver localized content.
Delivery endpoint v2
Version 2 was introduced with Magnolia REST 2.1 and provides more flexibility. You can use it to define multiple endpoint configurations, deliver localized content and resolve references to nodes of other workspaces including assets and asset renditions.
Delivery endpoint v1
Version 1 was introduced with Magnolia REST 2.0. You can configure a single endpoint for your project.
| Note |
|---|
Version 1 is deprecated, but you can still use it if required. We recommend you use the newer version 2. |
...
Search nodes in the tours workspace which contain the keyword vietnam . Return the results in descending order by the location property and restrict the limit to one:
| Code Pro |
|---|
curl -X GET 'http://localhost:8080/magnoliaAuthor/.rest/delivery/tours/v1?q=vietnam&orderBy=location%20desc&limit=1' \
-u superuser:superuser |
| Expand | |||||||
|---|---|---|---|---|---|---|---|
| |||||||
The result is based on the basic configuration.
|
find a tour and filter with the description property (Get photobombed by a Sea Turtle):
| Code Block |
|---|
curl -X GET \
'http://localhost:8080/magnoliaAuthor/.rest/delivery/tours/v1?description=Get%20photobombed%20by%20a%20Sea%20Turtle' \
-u superuser:superuser |
| Expand | |||||||
|---|---|---|---|---|---|---|---|
| |||||||
The result is based on the basic configuration. |
Search all ancestor nodes of the /travel/about/careers/marketing-associate page from the website workspace:
| Code Block |
|---|
curl -X GET \
'http://localhost:8080/magnoliaAuthor/.rest/delivery/website/v1?@ancestor=/travel/about/careers/marketing-associate' \
-u superuser:superuser |
...
| MultiExcerptName | configuration |
|---|
The delivery endpoint requires a configuration, which can be done in YAML file or via JCR, otherwise, it cannot deliver content. Version 2.0 of the magnolia-rest-content-delivery module can have only one configuration. You can decorate the definition. Future versions will allow multiple configurations which can be distinguished via a URL parameter.
Add the configuration to the restEndpoints folder in a light module or within src/main/resources/<module-name>/restEndpoints in a Magnolia Maven module.
...
| Code Pro | ||||
|---|---|---|---|---|
| ||||
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:
...
required
Must be info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpointDefinition or a subclass.
...
optional default=info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpoint
Must be info.magnolia.rest.delivery.jcr.v1.JcrDeliveryEndpoint or a subclass.
...
required
The map defining at least one or more endpoint prefixes.
...
<endpointPrefix>
...
required
Defines an endpoint prefix where requests will be routed and handled according to the associated workspace parameters below.
The value can be an arbitrary name (no special characters!) - 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
...
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 |
...
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.
...
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 | ||||
|---|---|---|---|---|
| ||||
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 :
...
<reference-name>
...
An arbitrary name for a
| Javadoc resource link | ||||
|---|---|---|---|---|
|
...
propertyName
...
referenceResolver
...
The reference resolver definition for this reference. Its definition class is
| Javadoc resource link | ||||
|---|---|---|---|---|
|
...
implementationClass
...
A class implementing
| Javadoc resource link | ||||
|---|---|---|---|---|
|
Current implementations:
| Javadoc resource link | ||||
|---|---|---|---|---|
|
...
targetWorkspace
...
| title | Click to see a response with resolved references |
|---|
...
| language | js |
|---|
...
Overview
Content Tools