Content HAL API - BloomReach Experience - Open Source CMS

Content HAL API

BloomReach offers Enterprise support for this feature to BloomReach Experience customers. The release cycle of this feature may differ from our core product release cycle. 

Content HAL API Add-on provides various built-in APIs to retrieve collection of data, an item of data, resource bundles or taxonmies. 

APIs to Retrieve Collection of Documents

You can retrieve a collection of documents through /documents REST API endpoint like the following example:

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

So, the example request shown above will retrieve all the documents in CMS, regardless of document types.

If you want to retrieve a collection of a specific document type only instead, then you can replace /douments in URL by the specific document type name like the following example:

  • 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
  • ...

The first example will retrieve all the news documents only whereas the second one will retrieve all the events documents only. You can use the physical document type name such as myproject:newsdocument in the URL instead of the logical name, "newsdocument" as shown in the last two examples, too. e.g, http://localhost:8080/site/api/myproject:newsdocument. In general, unless you have same logical document type name in different namespaces, it might be more intuitive to use the logical names (e.g, "newsdocument") instead of physical names (e.g, "myproject:newsdocument").

This kind of document collection retrieval APIs support the following query parameters in common.

[Common Query Parameters]

Name

Required

Description

Examples

_scope

No

Search scope node ID or path.
The base content node for the API mount by default.

_scope=a_UUID or
_scope=/content/documents/myproject/news

_offset

No

Offset of the iterating query result.
0 by default.

_offset=10

_limit

No

Limit of the iterating query result.
10 by default.

_limit=10

_fields

No

Comma-separated field names to include or exclude.
By default, include every field in response if not specified.

Note: If a field name is prefixed by "-", it means to exclude that specific field.
You can also use "*" to include every field explicitly. e.g, _fields=*,-content

_fields=title,introduction,-content

_sort

No

Comma-separated sort field names.
No sorting by default.

Note: If a field name is prefixed by "-", the specific field will be sorted in descending order.
If a field name is included but not prefixed by "-", the field will be sorted in ascending order.

_sort=title,-date

_q

No

Full text search query term which is used in jcr:contains(.,q) constraint in the query.

_q=lorem+ipsum

_expr

No

Custom JCR XPath expression to narrow the search result.

_expr=jcr:contains(@my:title,'hippo')

APIs to Retrieve Single Document

You can retrieve single document by UUID or relative path under the mount's content base path. For example,

  • 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, suppose you have a news article document at /content/documents/myproject/news/2017/02/the-medusa-news and its UUID is c580ac64-3874-4717-a6d9-e5ad72080abe, then you can retrieve the content by any of the following URL examples:

  • 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

This kind of single document retrieval APIs support the following query parameters in common.

[Common Query Parameters]

Name

Required

Description

Examples

_fields

No

Comma-separated field names to include or exclude.
By default, include every field in response if not specified.

Note: If a field name is prefixed by "-", it means to exclude that specific field.
You can also use "*" to include every field explicitly. e.g, _fields=*,-content

_fields=title,introduction,-content

APIs to Retrieve Folders

Content HAL API Add-on also supports retrievals on content folders. To retrieve a collection of folders, invoke /folders REST API endpoint:

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

This API supports the following query parameters:

Name

Required

Description

Examples

_offset

No

Offset of the iterating query result.
0 by default.

_offset=10

_limit

No

Limit of the iterating query result.
10 by default.

_limit=10

_sort No Comma-separated sort field names.
No sorting by default.

Note: If a field name is prefixed by "-", the specific field will be sorted in descending order.
If a field name is included but not prefixed by "-", the field will be sorted in ascending order.
 

_q

No

Full text search query term which is used in jcr:contains(.,q) constraint in the query.

_q=lorem+ipsum

_expr

No

Custom JCR XPath expression to narrow the search result.

_expr=jcr:contains(@my:title,'bloomreach')

You can also retrieve a specific folder content by specifying either UUID or relative folder path:

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

APIs to Retrieve Resource Bundles

Resource Bundle documents are special documents which are identified by Bundle ID (a.k.a, "basename"). So, Content HAL API Add-on supports dedicated APIs for Resource Bundle documents.

You can retrieve a collection of all the available Resource Bundles through /resourcebundles REST API endpoint like the following example:

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

This API supports the following query parameters:

Name

Required

Description

Examples

_offset

No

Offset of the iterating query result.
0 by default.

_offset=10

_limit

No

Limit of the iterating query result.
10 by default.

_limit=10

_q

No

Full text search query term which is used in jcr:contains(.,q) constraint in the query.

_q=lorem+ipsum

_expr

No

Custom JCR XPath expression to narrow the search result.

_expr=jcr:contains(@my:title,'hippo')

You can also retrieve single Resource Bundle data like the following example:

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

So, for example, you want to retrieve the Resource Bundle, the basename of which is essentials.global, by invoking the following URL:

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

This API supports the following query parameters:

Name

Required

Description

Examples

locale

No

Locale string. e.g, "en", "fr", "en_US", etc.
If not specified, it reads the resource bundle of the default locale.

locale=en

APIs to Retrieve Taxonomies (since 3.1.0)

Taxonomy documents are special documents which are identified by  taxonomyName which is the underlying node name. Content HAL API Add-on supports dedicated APIs for Taxonomy documents.

You can retrieve a collection of all the available taxonomies through /taxonomies REST API endpoint like the following example:

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

You can retrieve a single taxonomy data structure using:

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

This API supports the following query parameter:

Name

Required

Description

Examples

_depth

No The maximum depth of descendants to include.
0 means no descendant included and -1 means no limit. N (a positive integer) is not supported yet. -1 by default.

_depth=0

You can retrieve a single category data structure from the taxonomy using:

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

The last part of the URL {categoryPathOrKey} is either the category path or the category key, depending on _bypath query parameter.
For example, (1)  gives the data of the category at exampletaxonomy/level-1/level-2 whereas (2) gives the same data structure if level-2 has key "level-2-key": 

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

This API supports the following query parameters:

Name

Required

Description

Examples

_bypath No Whether categoryPathOrKey URL part should be treated as a category path or category key.
A boolean, true by default.
_bypath=false

_depth

No The maximum depth of descendants to include.
0 means no descendant included and -1 means no limit. N (a positive integer) is not supported yet. 0 by default.

_depth=-1

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?