Delivery API
This page describes the delivery endpoint for obtaining data as JSON with Magnolia SaaS.
The <magnolia-base-path> for the Delivery API is:
| URL | Description |
|---|---|
|
Use this URL for published content. This is content that is viewable on your site. |
|
Use this URL for unpublished content. This is content that you are still working on that isn’t yet published to your site. |
|
The methods, called with HTTP GET, allow you to:
|
Subscription ID tokens
In order to use the Delivery API, you must have your subid_token which is provided to you upon signing up for Magnolia SaaS.
Include the subid_token in the URL.
The query string and header based techniques to supply the subid_token are now deprecated.
|
Find your subscription ID here .
Environments
https://delivery.saas.magnolia-cloud.com/<subid_token>/<path>
If there is no environment (branch) specified in the URL, it defaults to the main branch.
|
https://delivery.saas.magnolia-cloud.com/<subid_token>/environments/<environment>/<path>
| Parameter | Description |
|---|---|
|
The specific endpoint such as
|
|
The environment (branch) such as
|
CORS
With Magnolia SaaS, Cross-Origin Resource Sharing (CORS) is currently fully open and system-wide CORS settings apply.
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,
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. -
Examples of using
inandnot-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-dd2018-01-01 -
Datetime:
yyyy-MM-dd’T’HH:mm:ss.SSSXXX2018-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
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
...