Published
- Jun 7, 2021
- 4 MIN
Author
-
Bartosz Staryga Front-End Solution Architect at Magnolia
Category
Tech
Topics
Share
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.
Endpoint definition in a Light Module
Delivery endpoint API configurations reside in the restEndpoints folder or one of its subfolders.
Java
my-light-module/
└── restEndpoints
├── delivery
│ └── another-endpoint.yaml
└── my-endpoint.yaml
The endpointPath property
The endpointPath provides access to a delivery endpoint.
Java
<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:
Java
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.
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.
Java
<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.
Java
<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:
Java
property[operator]=value
For example
Java
.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:
lang, for example, lang=de
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:
Java
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.
Java
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:
Nodes Endpoint API and Commands Endpoint API
About the Author