Headless Magnolia: The Delivery Endpoint API

by Bartosz Staryga, Front-End Solution Architect at Magnolia
Jun 7, 2021 | 4 MIN

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.

Endpoint definition in a Light Module

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

my-light-module/
└── restEndpoints
    ├── delivery
    │ └── another-endpoint.yaml
    └── my-endpoint.yaml

The endpointPath property

The endpointPath provides access to a delivery endpoint.

<magnolia-base-path>/.rest/endpointPath/{path}
<magnolia-base-path>/.rest/endpointPath?query-parameters

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

YAML definition

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

class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
workspace: website

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.

Using Magnolia as a headless CMS

Manage content in one hub and reuse it across the web and all your channels. See why Magnolia is great for headless—no need to sacrifice authoring experience and enterprise features.

Learn more

Methods

Read node

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.

<magnolia-base-path>/.rest/endpointPath/{path}

Query nodes

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

<magnolia-base-path>/.rest/endpointPath?param1=value1&=value2&...

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:

property[operator]=value

For example

.rest/my-endpoint?description[like]=%demonstration%.

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

Localized content

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

  1. lang, for example, lang=de

  2. Accept-Language, for example, Accept-Language: de

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.

Resolving references

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.

AssetReferenceResolverDefinition

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:

references:
 - name: imageReference
   propertyName: image
   referenceResolver:
     class: info.magnolia.rest.reference.dam.AssetReferenceResolverDefinition

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.

JcrReferenceResolverDefinition

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

references:
 - name: tourTypeReference
   propertyName: tourTypes
   referenceResolver:
     class: info.magnolia.rest.reference.jcr.JcrReferenceResolverDefinition
     targetWorkspace: category

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

Get started with delivery endpoints in Magnolia

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!

Learn more about Magnolia’s headless features

We plan to cover the following topics next:

  1. Security configuration and CORS

  2. SPA in Light Development

  3. SPA as a Magnolia template

  4. Virtual URI mapping

  5. Hosting a SPA outside of Magnolia

  6. Nodes endpoint API and Commands endpoint API

About the Author

Bartosz is an expert in headless content management and front-end development at Magnolia. He designs and develops new Magnolia features and supports customers with their headless implementations from content types to APIs to integrations. Bartosz enjoys building new things and seeing them in action. He is also a trainer for Magnolia’s Headless training.