Headless Magnolia: The Delivery Endpoint API

If you want to learn about Magnolia’s take on headless content management but don't know where to start, you've come to the right place. As part of our “Headless Magnolia” series, we’ll break down relevant features that allow you to use Magnolia as a headless CMS. In this article, we’ll discuss the delivery endpoint API.

The delivery endpoint API provides JCR data as JSON. The API is customizable and flexible to use. You can create multiple endpoint configurations, deliver localized content, and resolve references to nodes in other workspaces, including assets and asset renditions.

Delivery endpoint API configurations reside in the restEndpoints folder or one of its subfolders.

The endpointPath provides access to a delivery endpoint.

To include the endpoint’s version number in the endpoint’s path, add _v$number to its YAML file name.

The most basic YAML configuration for a delivery endpoint contains only 2 lines:

class defines the Java class that handles the endpoint.

workspace is the name of the JCR workspace from which to deliver content.

You can customize the endpoint definition using parameters.

depth specifies how deep the node tree will be traversed.

includeSystemProperties specifies whether the result should show system properties.

limit specifies the number of nodes in the result.

You can find a list of all supported configuration options in our documentation.

This method 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.

This method returns a list of nodes matching the query parameters. You can also apply filters to the query.

A couple of useful query parameters are:

orderBy dictates the properties used to order the nodes. As of Magnolia 6.2.6, sorting is case-insensitive.

limit specifies the number of nodes to be displayed in a page query.

You can also add one or multiple filters as request parameters. Their values must be properly URL-encoded. The filter parameter has the following format:

For example

A complete list of filter operators is available in our documentation.

There are two parameter options to request content of a specific language variant:

If both parameters are set, the lang parameter takes priority. If neither is set, the fallback language is used.

To return all language variants, set the lang parameter to lang=all.

The delivery endpoints return content as JSON from the JCR workspace configured by the workspace property.

The image property contains an asset identifier that refers to an asset. In this example, the asset is stored in the Magnolia DAM in the dam workspace.

We could subsequently request content from the DAM workspace. However, it is more efficient to resolve the references within the initial request using one of Magnolia’s reference resolvers.

This Magnolia reference resolver operates on the DAM workspace. It can also generate links to asset renditions if the referenced assets reside in the Magnolia DAM.

To add this reference resolver, extend the endpoint’s YAML definition:

name is an arbitrary revolver name.

propertyName is the name of the property you want to resolve.

referenceResolver is the resolver you want to use.

This Magnolia reference resolver operates on a specific target workspace. It resolves properties to raw JCR data.

targetWorkspace specifies the name of the workspace that contains the referenced nodes.

Creating a new endpoint in Magnolia is quick, easy, and flexible. You don’t need help from specialized back-end developers to create new endpoints to deliver data. Test it yourself and create one endpoint today!

We plan to cover the following topics next: