Delivery API - CDS
The information on this documentation page is not yet applicable in production. |
This page describes the Delivery endpoint for obtaining Content Data Source (CDS) 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
property and provides three methods. The methods, called with HTTP GET, allow you to 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:
-
Use
delivery
as part of the endpoint path. Our webapps come with a pre-configured user role calledrest-anonymous
, which allows anonymous users to access the/.rest/delivery/*
path. -
Set the
bypassWorkspaceAcls
property totrue
in all endpoint configurations.
Methods
Read node
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.
Request URL
GET <magnolia-base-path>/endpointPath/{path}
Parameters
Parameter | Description | Data type |
---|---|---|
|
required, default is The path relative to the |
|
|
optional, default is Specifies how deep the node tree will be traversed. If you use the default value, no tree is returned. |
|
Get children
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:
Request URL
GET <magnolia-base-path>/endpointPath/{path}@nodes
The items in the response are returned in their natural (unsorted) order. |
Parameters
Parameter | Description | Data type |
---|---|---|
|
required The path relative to the |
|
|
optional The start position in a result list. |
|
|
optional The number of results to be displayed. |
|
|
optional Specifies how deep the node tree will be traversed. By default, the value set in the endpoint definition is applied. You can override it by setting a new value as |
|
|
optional, default is Controls whether |
|
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>/endpointPath?param1=value1¶m2=value2&…
Parameters
Parameter | Description | Data type |
---|---|---|
|
optional A search phrase (full-text search). |
|
|
optional The start position in a result list (for pagination). Default is |
|
|
optional The number of results to be displayed. |
|
|
optional Specifies how deep the node tree will be traversed. By default, the value set in the endpoint definition is applied. You can override it by setting a new value as |
|
|
optional, default is Controls whether |
|
|
optional There are multiple filter options to filter for:
You can combine filters using the |
Filters
queryNodes
provides a filtering mechanism. Filters are added as request parameters. You can use multiple filters within the same request.
Filter values must be properly URL-encoded. In some REST clients, you may need to URL-encode also the key in the filter parameter. For example:
See also Section 2.2 of the RFC standard called Uniform Resource Identifier (URI): Generic Syntax. |
Filtering
Filter operators
Operator | Meaning |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Can be used with:
|
Can be used with: Percentage - Wildcard character that can be used in the search pattern to mean zero or more additional characters. Underscore - Wildcard character that can be used in the search pattern to stand for any single character. |
|
The value can be either For example, The operator can be used with any property. |
Filter types
Property | Description |
---|---|
|
Filter by a node name.
|
|
Filter by a node ID (UUID). The property value must be an exact match.
|
|
Filter by a path.
|
|
Filter by a specific version of a content item.
|
Usage notes
-
If no operator is provided,
eq
is used by default. -
The
value
in the filter parameter is treated asString
. -
Use brackets to pass an operator, for example
[eq]
,[ne]
,[lt]
, and so on. -
Examples of using
in
andnot-in
:fruit[in]=apple,grapes,orange
,fruit[not-in]=apple,grapes,orange
-
Range example:
price[gte]=100&price[lte]=200
, 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
2018-01-01
-
Datetime:
yyyy-MM-dd’T’HH:mm:ss.SSSXXX
2018-01-11T10:26:47.438+07:00
-
Configuration
Endpoint path
You can define multiple endpoints. At runtime, the endpoint path for each endpoint is generated automatically from the path and name of the respective endpoint definition.
- Examples
File path | Endpoint path |
---|---|
|
|
|
|
|
|
|
|
Location of the endpoint definitions
Magnolia REST endpoint definitions are true Magnolia Resources . You can create them in:
-
a light module
-
a Magnolia Maven module
In a light module
Add configurations to the folder restEndpoints
or to subfolders.
my-light-module/ └── restEndpoints ├── delivery │ └── another-endpoint.yaml └── my-endpoint.yaml
In a Magnolia Maven module
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
Best practice Put the delivery endpoint configurations under the |
Properties
Property | Description | ||
---|---|---|---|
|
required Possible values:
Example The following is a minimum configuration required to read the $type: pagesDeliveryEndpoint_v2 (1) workspace: website
|
||
|
required Name of the target workspace to serve content from. |
||
|
optional Defines the root path used to resolve the given node path parameter and to execute queries. |
||
|
optional A list of allowed node types. |
||
|
optional Defines the depth of child nodes to be included in the responses. The depth is relative to result nodes. |
||
|
optional, default is Defines whether to include only the exact node type and ignore the sub types. If |
||
|
optional A list of content properties to be returned.
|
||
|
optional A list of allowed content types of child nodes. See also the complementary |
||
|
optional, default is This property complements the
Example You want to include all page properties that are part of a page dialog except areas and components. Then, you would need to configure an empty |
||
|
optional, default is Defines the number of results to be returned in a paginated result set. |
||
|
optional This property allows you to resolve referenced through a list of reference definitions. The properties of a single reference are defined in For configuration of reference definitions, see the Properties for resolving references subsection below this table. Example configuration with an asset resolver
|
||
|
optional, default is Defines on how many levels the references should be considered and returned in a response if found. |
||
|
optional, default is The default setting eliminates resolving self-references. |
||
|
optional, default is Defines whether
|
||
|
optional Defines which |
Properties for resolving references
The references
property node contains a list of reference definitions.
Property | Description |
---|---|
|
optional An arbitrary name. If you do not set the property, the first property must start with a Using the |
|
required The value of this property contains the name of the node property that stores one or multiple references to nodes of other workspaces. |
|
required The reference resolver defines how references are resolved. The properties are defined in info.magnolia.rest.reference.ReferenceResolverDefinition. For configurable properties, see further below: Example configuration
|
referenceResolver properties for resolving CDS references
Property | Description | ||
---|---|---|---|
|
required Must be |
||
|
optional, default is If set to If |
||
|
optional
A YAML map with named UUID resolvers. For each resolver you must define the following properties:
|
||
|
optional, default is Sets the depth in the referenced nodes. The default value of |
Example configuration
...
- name: page
propertyName: page
referenceResolver:
$type: norsuReferenceResolver
targetWorkspace: website
expand: true
- name: simpleModel
propertyName: simpleModel
referenceResolver:
$type: norsuReferenceResolver
targetWorkspace: magnolia-travels
expand: true
...
referenceResolver properties for resolving asset references
Property | Description |
---|---|
|
required Must be |
|
optional, default is If set to If |
|
optional, default is If set to |
|
optional, default is If set to |
|
optional A list of rendition names as defined in the theme linked to the current site. |
|
required The rendition name. To get the asset in its original (default) size, use If you add an undefined – and therefore non-existent rendition – the asset resolver creates a link to the default variation which is the same as the asset in its original size. Example:
|
referenceResolver properties for resolving asset links in rich text fields
Property | Description | ||
---|---|---|---|
|
required Must be |
||
|
optional, default is If set to If |
||
|
optional
A YAML map with named UUID resolvers. For each resolver you must define the following properties:
|
Example configuration
...
- name: pageNorsuRichTextReferenceResolver
propertyName: richtext-page
referenceResolver:
$type: norsuRichTextReferenceResolver
- name: damNorsuRichTextReferenceResolver
propertyName: richtext-dam
referenceResolver:
$type: norsuRichTextReferenceResolver
...