Content HAL API

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 /documents 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]

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]

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:

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:

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:

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:

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: