Documentation Powered by ReDoc

Magnolia Delivery Endpoints API

Download OpenAPI specification:Download

This illustrates the key aspects of getting content from Delivery Endpoints.

In Magnolia, you create your own endpoints via configuration to match your needs.

We provide the output of two example content types: Tours and Pages.

Tours

An example of working with a standard Magnolia content type.
We use tours as a concrete example here, but the format will apply to any delivery endpoint that you create.

The tours collection has the following extra properties:

  • name
  • location
  • author
  • body
  • duration
  • image
  • tourTypes
  • destinations

Pages

An endpoint that returns Pages from the website workspace - an important special case.
A Page has a heirarchy of Areas and Components, so the endpoint returns a tree. Different properties will be returned on each node, depending on the dialog associated with the page template or component template.

Tours Endpoint

List tours (Query nodes)

If no orderBy parameter is used, the order of the results is unknown.
It probably will not be the same order of the items seen by users in the AdminCentral Magnolia UI.

query Parameters
lang
string

In which language to return the content. By default, returns the language based on Accept-Language header. Takes the language code (i.e. de, de-DE), or all to return all content.

limit
integer <int32>

How many tours to return at one time (Default can be specified in endpoint configuration)

offset
integer <int32>

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

orderBy
string

The properties by which to order the nodes. The result may be returned either in the ascending ( asc ) order or in the descending ( desc ) order. The ascending order is applied if the direction is not set.
Example: mgnl:lastModified desc,title asc

q
string

A search phrase (full-text search).

<filter>
string

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: name[like]=%25Families%25
Example:
http://localhost:8080/magnoliaAuthor/.rest/delivery/tours?name[like]=%25Families%25&duration=7

Operator Meaning
eq =
ne <>
gt >
lt <
lte <=
gte >=
in IN
not-in NOT IN
like LIKE
null NULL

Filters are case-sensitive.

For in and not-in:
Tilde ~ is the range symbol. Example: price[in]=100~200.

For like:
% is a wildcard for 0 or more characters.\ _ is a wildcard for 1 character.

For filtering by date and time:
only two ISO 8601-based formats are accepted. The patterns shown are in JAVA notation.
Date: yyyy-MM-dd (Example: 2018-01-01)\ Datetime: yyyy-MM-dd'T'HH:mm:ss.SSSXXX (Example 2018-01-11T10:26:47.438+07:00)

For filtering within a language:
Keep in mind that properties in the default language have no suffix, while properties in other languages are suffixed with the language code. Consider the 'travel demo', where English is the default language, you could actually have 3 properties: body, body_de, body_fr.
In your query you need to specify the actual property name you want to filter.
Examples: body[like]=%Experience% and body_de[like]=%Erleben%

If a filter can take multiple possible values , use | (OR):
Example: @name=travel|about

Special filter properties

You can filter on additional special properties that you don't see in the endpoint response.

@jcr:uuid filter
Filter by the JCR node ID (uuid). The property value must be an exact match.

@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. Example: @ancestor=/travel/about/careers/marketing-associate

Responses

200

An array of tours

default

Unexpected Error

get /tours
http://localhost:8080/magnoliaAuthor/.rest/delivery/tours

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "results":
    [
    ]
}

Get a tour (Read node)

This API will return child nodes in their 'natural order', the same order that users give items in the AdminCentral Magnolia UI.
(With the 'Query nodes' API, the array of responses may not be in their 'natural order' )

To get only the children of the item specified with the path, append @nodes to the end of the query. (This is called the 'Get children' API in the full documentation.)

Note: To get an item by its id or other property you can use a query as described above in the 'Query nodes' API.

path Parameters
path
required
string

The path of the page to retreive. Example: /magnolia-travels/A-Taste-of-Malaysia.

Responses

200

Expected response to a valid request

default

Unexpected Error

get /tours/{tourPath}[@nodes]
http://localhost:8080/magnoliaAuthor/.rest/delivery/tours/{tourPath}[@nodes]

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "@id": "a358f3ad-5a03-4f5d-b0ab-cb2219100472",
  • "@path": "/magnolia-travels/A-Taste-of-Malaysia",
  • "@name": "A-Taste-of-Malaysia",
  • "@nodeType": "string",
  • "@nodes": [ ],
  • "mgnl:tags": [ ],
  • "mgnl:created": "2015-07-01T08:50:23.426Z",
  • "mgnl:createdBy": "superuser",
  • "mgnl:lastModified": "2015-07-01T08:50:23.426Z",
  • "mgnl:lastModifiedBy": "superuser",
  • "mgnl:lastActivated": "2015-07-01T08:50:23.426Z",
  • "mgnl:lastActivatedBy": "superuser",
  • "name": "string",
  • "location": "string",
  • "author": "string",
  • "body": "string",
  • "duration": "string",
  • "image":
    {
    },
  • "tourTypes":
    [
    ],
  • "destinations":
    [
    ]
}

Pages Endpoint

List pages (Query nodes)

If no orderBy parameter is used, the order of the results is unknown.
It probably will not be the same order of the items seen by users in the AdminCentral Magnolia UI.

query Parameters
lang
string

In which language to return the content. By default, returns the language based on Accept-Language header. Takes the language code (i.e. de, de-DE), or all to return all content.

limit
integer <int32>

How many tours to return at one time (Default can be specified in endpoint configuration)

offset
integer <int32>

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

orderBy
string

The properties by which to order the nodes. The result may be returned either in the ascending ( asc ) order or in the descending ( desc ) order. The ascending order is applied if the direction is not set.
Example: mgnl:lastModified desc,title asc

q
string

A search phrase (full-text search).

<filter>
string

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: name[like]=%25Families%25
Example:
http://localhost:8080/magnoliaAuthor/.rest/delivery/tours?name[like]=%25Families%25&duration=7

Operator Meaning
eq =
ne <>
gt >
lt <
lte <=
gte >=
in IN
not-in NOT IN
like LIKE
null NULL

Filters are case-sensitive.

For in and not-in:
Tilde ~ is the range symbol. Example: price[in]=100~200.

For like:
% is a wildcard for 0 or more characters.\ _ is a wildcard for 1 character.

For filtering by date and time:
only two ISO 8601-based formats are accepted. The patterns shown are in JAVA notation.
Date: yyyy-MM-dd (Example: 2018-01-01)\ Datetime: yyyy-MM-dd'T'HH:mm:ss.SSSXXX (Example 2018-01-11T10:26:47.438+07:00)

For filtering within a language:
Keep in mind that properties in the default language have no suffix, while properties in other languages are suffixed with the language code. Consider the 'travel demo', where English is the default language, you could actually have 3 properties: body, body_de, body_fr.
In your query you need to specify the actual property name you want to filter.
Examples: body[like]=%Experience% and body_de[like]=%Erleben%

If a filter can take multiple possible values , use | (OR):
Example: @name=travel|about

Special filter properties

You can filter on additional special properties that you don't see in the endpoint response.

@jcr:uuid filter
Filter by the JCR node ID (uuid). The property value must be an exact match.

@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. Example: @ancestor=/travel/about/careers/marketing-associate

Responses

200

An array of pages

default

Unexpected Error

get /pages
http://localhost:8080/magnoliaAuthor/.rest/delivery/pages

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "results":
    [
    ]
}

Get a page (Read node)

This API will return child nodes in their 'natural order', the same order that users give items in the AdminCentral Magnolia UI.
(With the 'Query nodes' API, the array of responses may not be in their 'natural order' )

To get only the children of the item specified with the path, append @nodes to the end of the query. (This is called the 'Get children' API in the full documentation.)

Note: To get an item by its id or other property you can use a query as described above in the 'Query nodes' API.

path Parameters
path
required
string

The path of the page to retreive. Example: /magnolia-travels/A-Taste-of-Malaysia.

Responses

200

Expected response to a valid request

default

Unexpected Error

get /pages/{pagePath}[@nodes]
http://localhost:8080/magnoliaAuthor/.rest/delivery/pages/{pagePath}[@nodes]

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "@id": "a358f3ad-5a03-4f5d-b0ab-cb2219100472",
  • "@path": "/magnolia-travels/A-Taste-of-Malaysia",
  • "@name": "A-Taste-of-Malaysia",
  • "@nodeType": "mgnl:page",
  • "@nodes": [ ],
  • "mgnl:tags": [ ],
  • "mgnl:created": "2015-07-01T08:50:23.426Z",
  • "mgnl:createdBy": "superuser",
  • "mgnl:lastModified": "2015-07-01T08:50:23.426Z",
  • "mgnl:lastModifiedBy": "superuser",
  • "mgnl:lastActivated": "2015-07-01T08:50:23.426Z",
  • "mgnl:lastActivatedBy": "superuser",
  • "mgnl:template": "react-minimal-lm:pages/basic",
  • "main":
    {
    },
  • "extras":
    {
    }
}