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 called rest-anonymous, which allows anonymous users to access the /.rest/delivery/* path.

  • Set the bypassWorkspaceAcls property to true 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

path

required, default is /

The path relative to the rootPath defined in the configuration.

String

depth

optional, default is 0

Specifies how deep the node tree will be traversed.

If you use the default value, no tree is returned.

Integer

Example

Get all component nodes of the main area of the /travel/about page.

curl "https://delivery.saas.magnolia-cloud.com/delivery/myEndpoint/travel/about/main?subid_token=YOUR_subid_token"

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

path

required

The path relative to the rootPath defined in the configuration.

String

offset

optional

The start position in a result list.

Long

limit

optional

The number of results to be displayed.

Integer

depth

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 depth HTTP query param.

Integer

includesTotal

optional, default is false

Controls whether total is included in a paged response.

Boolean

Example

Get child nodes in the root of the /travel page:
curl "https://delivery.saas.magnolia-cloud.com/delivery/myEndpoint/travel/@nodes?subid_token=YOUR_subid_token"

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&param2=value2&…​

Parameters
Parameter Description Data type

q

optional

A search phrase (full-text search).

String

offset

optional

The start position in a result list (for pagination). Default is 0.

Long

limit

optional

The number of results to be displayed.

Integer

depth

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 depth HTTP query param.

Integer

includesTotal

optional, default is false

Controls whether total is included in a paged response.

Boolean

<filter>

optional

There are multiple filter options to filter for:

  • a property of the node

  • node names

  • nodes which must be ancestors of a given path

You can combine filters using the AND operator.

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: https://delivery.saas.magnolia-cloud.com/myEndpoint?description%5Blike%5D=%25demonstration%25

See also Section 2.2 of the RFC standard called Uniform Resource Identifier (URI): Generic Syntax.
Filter format

The filter parameter has the following format: property[operator]=value

Example filter used in a URL
https://delivery.saas.magnolia-cloud.com/myEndpoint?description[like]=%25demonstration%25

Filtering

Filter operators

Operator Meaning

eq

=

ne

<>

gt

>

lt

<

lte

<=

gte

>=

in

IN

not-in

NOT IN

like

Can be used with:

% (percentage, URL encoded as %25)

_ (underscore)

LIKE

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.

null

NULL

The value can be either true or false.

For example, mgnl:created[null]=false.

The operator can be used with any property.

Filter types

Property Description

@name property filter

Filter by a node name.

@name=travel

@id filter

Filter by a node ID (UUID). The property value must be an exact match.

@id=f3c4e3fb-60d0-4231-a125-958da55f7641

@path filter

Filter by a path.

@path=/travel/about/careers/

@version filter

Filter by a specific version of a content item.

@version=1.2

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.

  • Examples of using in and not-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

/<module-name>/restEndpoint/stories.yaml

/.rest/stories

/<module-name>/restEndpoint/delivery/stories.yaml

/.rest/delivery/stories

/<module-name>/restEndpoint/stories/v3.yaml

/.rest/stories/v3

/<module-name>/restEndpoint/delivery/stories_v3.yaml

/.rest/delivery/stories/v3

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 delivery subfolder.

Properties

Property Description

$type

required

Possible values:

  • deliveryEndpoint_v2

  • pagesDeliveryEndpoint_v2

Example

The following is a minimum configuration required to read the mgnl:page content, in this example stored in the website workspace.

$type: pagesDeliveryEndpoint_v2 (1)
workspace: website
1 The pagesDeliveryEndpoint_v2 alias represents a pre-configured node type resolver definition for pages to produce JSON v2 responses. The resolver is provided by the magnolia-pages-norsu-rest module. The includeSystemProperties defaults to true in this case.

workspace

required

Name of the target workspace to serve content from.

rootPath

optional

Defines the root path used to resolve the given node path parameter and to execute queries.

nodeTypes

optional

A list of allowed node types.

depth

optional

Defines the depth of child nodes to be included in the responses.

The depth is relative to result nodes.

strict

optional, default is false

Defines whether to include only the exact node type and ignore the sub types.

If true, then it is applied to both the nodeTypes and the childNodeTypes.

contentProperties

optional

A list of content properties to be returned.

If no list is defined, all properties are returned. An empty list doesn’t return anything.

childContentTypes

optional

A list of allowed content types of child nodes.

See also the complementary includeNonTypeChildContent property.

includeNonTypeChildContent

optional, default is false

This property complements the childContentTypes property. If includeNonTypeChildContent is set to true, non-type content is also delivered together with the types defined using childContentTypes.

By "non-type content" we mean composite properties or any nested content that does not have a mgnl:type property.

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 childContentTypes list together with includeNonTypeChildContent=true.

limit

optional, default is 10

Defines the number of results to be returned in a paginated result set.

references

optional

This property allows you to resolve referenced through a list of reference definitions.

The properties of a single reference are defined in info.magnolia.rest.reference.ReferenceDefinition.

For configuration of reference definitions, see the Properties for resolving references subsection below this table.

Example configuration with an asset resolver

...
references:
  - name: referenceWithAsset
    propertyName: assetLink
    referenceResolver:
      $type: assetReferenceResolver
      assetRenditions:
        - 320x240
...

referenceDepth

optional, default is 1

Defines on how many levels the references should be considered and returned in a response if found.

referenceRepeat

optional, default is false

The default setting eliminates resolving self-references.

includeSystemProperties

optional, default is false

Defines whether jcr:- and mgnl:- prefixed properties will be included in responses.

Defaults to true in case the $type is set to pagesDeliveryEndpoint_v2.

systemProperties

optional

Defines which jcr:- and mgnl:-prefixed properties will be included in responses.

Properties for resolving references

The references property node contains a list of reference definitions.

Property Description

name

optional

An arbitrary name. If you do not set the property, the first property must start with a - in order to have proper YAML list item.

Using the name property improves the readability of the YAML file.

propertyName

required

The value of this property contains the name of the node property that stores one or multiple references to nodes of other workspaces.

referenceResolver

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:
      $type: assetReferenceResolver
      assetRenditions:
        - 320x240
...

referenceResolver properties for resolving CDS references

Property Description

$type

required

Must be norsuReferenceResolver.

expand

optional, default is true

If set to true, all properties of the referenced node are included in the JSON.

If false, the JSON contains only links to the referenced node.

uuidResolvers

optional

There are default UUID link resolver configurations for the dam and website workspaces.

A YAML map with named UUID resolvers. For each resolver you must define the following properties:

  • uuid - The UUID of the node.

  • repository - The repository where the node is located, for example website or dam.

  • path - The relative path from the root of the repository to the node.

depthInReferencedNode

optional, default is -1

Sets the depth in the referenced nodes.

The default value of -1 means that the endpoint returns the referenced nodes up to the configured referenceDepth property (a specific depth for the returned "root" nodes) but it also returns all their children.

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

$type

required

Must be assetReferenceResolver.

expand

optional, default is true

If set to false, neither the list of defined renditions nor the meta data is shown.

If includeDownloadLink is set to true, a link is returned, otherwise the asset item key or original text is shown.

includeDownloadLink

optional, default is true

If set to false, the JSON file does not show the relative asset link.

includeAssetMetadata

optional, default is true

If set to false, metadata is not included.

assetRenditions

optional

A list of rendition names as defined in the theme linked to the current site.

     <rendition-name>

required

The rendition name.

To get the asset in its original (default) size, use original as the value.

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:

...
references:
  - name: referenceWithAsset
    propertyName: assetLink
    referenceResolver:
      $type: assetReferenceResolver
      assetRenditions:
        - 320x240
...

referenceResolver properties for resolving asset links in rich text fields

Property Description

$type

required

Must be norsuRichTextReferenceResolver.

expand

optional, default is true

If set to true, all properties of the referenced node are included in the JSON.

If false, the JSON contains only links to the referenced node.

uuidResolvers

optional

There are default UUID link resolver configurations for the dam and website workspaces.

A YAML map with named UUID resolvers. For each resolver you must define the following properties:

  • uuid - The UUID of the node.

  • repository - The repository where the node is located, for example website or dam.

  • path - The relative path from the root of the repository to the node.

Example configuration

...
  - name: pageNorsuRichTextReferenceResolver
    propertyName: richtext-page
    referenceResolver:
      $type: norsuRichTextReferenceResolver
  - name: damNorsuRichTextReferenceResolver
    propertyName: richtext-dam
    referenceResolver:
      $type: norsuRichTextReferenceResolver
...
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the REST module docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules