Content HAL API

Info: Bloomreach provides Enterprise support for this feature for Bloomreach Experience customers. The release cycle for this feature may differ from the core product release cycle.

The Content HAL API Add-on offers built-in REST APIs to retrieve collections of data, individual items, resource bundles, and taxonomies.

Retrieve a Collection of Documents

Use the /documents REST API endpoint to retrieve a collection of documents:

• http://localhost:8080/site/api/documents

This endpoint returns all documents in the CMS, regardless of document type.

To retrieve documents of a specific type, replace /documents in the URL with the desired document type name:

• http://localhost:8080/site/api/newsdocument
• http://localhost:8080/site/api/eventsdocument
• http://localhost:8080/site/api/myproject:newsdocument
• http://localhost:8080/site/api/myproject:eventsdocument

For example, the first URL retrieves only news documents, and the second retrieves only events documents. You can use either the logical document type name (e.g., newsdocument) or the physical name including the namespace (e.g., myproject:newsdocument). Use logical names unless you have duplicate document type names across different namespaces.

The document collection endpoints support the following query parameters:

Common Query Parameters

Name	Required	Description	Examples
_scope	No	Search scope node ID or path. Defaults to the base content node for the API mount.	_scope=a_UUID or _scope=/content/documents/myproject/news
_offset	No	Offset for the query result. Defaults to 0.	_offset=10
_limit	No	Maximum number of results to return. Defaults to 10.	_limit=10
_fields	No	Comma-separated list of field names to include or exclude. By default, all fields are included. Prefix a field with "-" to exclude it. Use "*" to explicitly include all fields.	_fields=title,introduction,-content
_sort	No	Comma-separated list of fields to sort by. No sorting is applied by default. Prefix a field with "-" for descending order; otherwise, ascending order is used.	_sort=title,-date
_q	No	Full text search query term, used in the jcr:contains(.,q) constraint.	_q=lorem+ipsum
_expr	No	Custom JCR XPath expression to filter the results.	_expr=jcr:contains(@my:title,'hippo')

Retrieve a Single Document

You can retrieve a single document by UUID or by relative path under the mount's content base path. Use the following URL patterns:

• http://localhost:8080/site/api/documents/{UUID}
• http://localhost:8080/site/api/documents/{relPath}
• http://localhost:8080/site/api/newsdocument/{UUID}
• http://localhost:8080/site/api/newsdocument/{relPath}
• http://localhost:8080/site/api/eventsdocument/{UUID}
• http://localhost:8080/site/api/eventsdocument/{relPath}
• http://localhost:8080/site/api/myproject:newsdocument/{UUID}
• http://localhost:8080/site/api/myproject:newsdocument/{relPath}
• http://localhost:8080/site/api/myproject:eventsdocument/{UUID}
• http://localhost:8080/site/api/myproject:eventsdocument/{relPath}

For example, if you have a news article at /content/documents/myproject/news/2017/02/the-medusa-news with UUID c580ac64-3874-4717-a6d9-e5ad72080abe, you can retrieve it using any of the following URLs:

• http://localhost:8080/site/api/documents/c580ac64-3874-4717-a6d9-e5ad72080abe
• http://localhost:8080/site/api/documents/news/2017/02/the-medusa-news
• http://localhost:8080/site/api/newsdocument/c580ac64-3874-4717-a6d9-e5ad72080abe
• http://localhost:8080/site/api/newsdocument/news/2017/02/the-medusa-news
• http://localhost:8080/site/api/myproject:newsdocument/c580ac64-3874-4717-a6d9-e5ad72080abe
• http://localhost:8080/site/api/myproject:newsdocument/news/2017/02/the-medusa-news

Single document retrieval endpoints support the following query parameter:

Common Query Parameters

Name	Required	Description	Examples
_fields	No	Comma-separated list of field names to include or exclude. By default, all fields are included. Prefix a field with "-" to exclude it. Use "*" to explicitly include all fields.	_fields=title,introduction,-content

Retrieve Folders

The Content HAL API Add-on also provides endpoints for retrieving content folders. To retrieve a collection of folders, use:

• http://localhost:8080/site/api/folders

Supported query parameters:

Name	Required	Description	Examples
_offset	No	Offset for the query result. Defaults to 0.	_offset=10
_limit	No	Maximum number of results to return. Defaults to 10.	_limit=10
_sort	No	Comma-separated list of fields to sort by. No sorting is applied by default. Prefix a field with "-" for descending order; otherwise, ascending order is used.
_q	No	Full text search query term, used in the jcr:contains(.,q) constraint.	_q=lorem+ipsum
_expr	No	Custom JCR XPath expression to filter the results.	_expr=jcr:contains(@my:title,'bloomreach')

To retrieve a specific folder, specify either the UUID or the relative folder path:

• http://localhost:8080/site/api/folders/{UUID}
• http://localhost:8080/site/api/folders/{relPath}

Retrieve Resource Bundles

Resource Bundle documents are identified by their Bundle ID (also called basename). The Content HAL API Add-on provides dedicated endpoints for resource bundles.

To retrieve all available resource bundles:

• http://localhost:8080/site/api/resourcebundles

Supported query parameters:

Name	Required	Description	Examples
_offset	No	Offset for the query result. Defaults to 0.	_offset=10
_limit	No	Maximum number of results to return. Defaults to 10.	_limit=10
_q	No	Full text search query term, used in the jcr:contains(.,q) constraint.	_q=lorem+ipsum
_expr	No	Custom JCR XPath expression to filter the results.	_expr=jcr:contains(@my:title,'hippo')

To retrieve a single resource bundle by basename:

• http://localhost:8080/site/api/resourcebundles/{basename}

For example, to retrieve the resource bundle with basename essentials.global:

• http://localhost:8080/site/api/resourcebundles/essentials.global

Supported query parameter:

Name	Required	Description	Examples
locale	No	Locale string (e.g., "en", "fr", "en_US"). If not specified, the default locale is used.	locale=en

Retrieve Taxonomies (since 3.1.0)

Taxonomy documents are identified by their taxonomyName (the node name). The Content HAL API Add-on provides endpoints for taxonomy documents.

To retrieve all available taxonomies:

• http://localhost:8080/site/api/taxonomies

To retrieve a single taxonomy structure:

• http://localhost:8080/site/api/taxonomies/{taxonomyName}

Supported query parameter:

Name	Required	Description	Examples
_depth	No	Maximum depth of descendants to include. 0 means no descendants; -1 means no limit. Positive integers are not supported yet. Defaults to -1.	_depth=0

To retrieve a single category from a taxonomy, use:

• http://localhost:8080/site/api/taxonomies/{taxonomyName}/{categoryPathOrKey}

The {categoryPathOrKey} segment can be either the category path or the category key, depending on the _bypath query parameter.

For example:

1. http://localhost:8080/site/api/taxonomies/exampletaxonomy/level-1/level-2 (category path)
2. http://localhost:8080/site/api/taxonomies/exampletaxonomy/level-2-key?_bypath=false (category key)

Supported query parameters:

Name	Required	Description	Examples
_bypath	No	Determines whether {categoryPathOrKey} is treated as a category path or key. Boolean, defaults to true.	_bypath=false
_depth	No	Maximum depth of descendants to include. 0 means no descendants; -1 means no limit. Positive integers are not supported yet. Defaults to 0.	_depth=-1