Example Request/Response Payloads
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.
This page shows what each request and response payload looks like when invoking the built-in Content HAL APIs. For simplicity, HTTPie command (e.g, http) is used in the demonstrations below.
Retrieving Collection of Documents
The following example request (http://localhost:8080/site/api/documents/) returns a collection of documents. All the documents in the result are embedded in the "documents" property of the reserved "_embedded" property.
$ http http://localhost:8080/site/api/documents/
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Date: Tue, 29 Aug 2017 01:30:51 GMT
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
{
"_embedded": {
"documents": [
{
"_links": {
"self": {
"href": "http://localhost:8080/site/api/documents/9fd0ecd8-acd6-4946-8a29-d7913e326eee"
}
},
"_meta": {
"id": "9fd0ecd8-acd6-4946-8a29-d7913e326eee",
"locale": "en",
"name": "first-blog-post",
"path": "blog/2017/02/first-blog-post",
"type": "hippoaddoncontenthalapidemo:blogpost"
},
"authornames": [
"Hippo Author"
],
"authors": [
{
"_meta": {
"mirror": {
"id": "5a6e1136-dea0-4927-9130-9ce0a47b0189",
"path": "content/documents/hippoaddoncontenthalapidemo/blog/authors/Hippo Author"
},
"type": "hippo:mirror"
}
}
],
"categories": [
"cms",
"life"
],
"content": {
"_meta": {
"type": "hippostd:html"
},
"content": "<p>Contrary to popular belief, Lorem Ipsum is not simply random text...</p>"
},
"introduction": "Lorem Ipsum is simply dummy text of the printing and typesetting industry...",
"publicationdate": 1487085240000,
"title": "First blog post"
},
{
"_links": {
"self": {
"href": "http://localhost:8080/site/api/documents/5a6e1136-dea0-4927-9130-9ce0a47b0189"
}
},
"_meta": {
"id": "5a6e1136-dea0-4927-9130-9ce0a47b0189",
"locale": "en",
"name": "Hippo Author",
"path": "blog/authors/Hippo Author",
"type": "hippoaddoncontenthalapidemo:author"
},
"accounts": [
{
"_meta": {
"type": "hippoaddoncontenthalapidemo:account"
},
"link": "https://github.com/onehippo",
"type": "github"
},
{
"_meta": {
"type": "hippoaddoncontenthalapidemo:account"
},
"link": "https://twitter.com/onehippo",
"type": "twitter"
}
],
"content": {
"_meta": {
"type": "hippostd:html"
},
"content": "<p>Hippo CMS is a powerful, enterprise-class foundation to deliver outstanding Customer Experiences based on Enterprise Agility and Innovation Power...</p>"
},
"fullname": "Hippo Author",
"photo": {
"_meta": {
"mirror": {
"id": "cafebabe-cafe-babe-cafe-babecafebabe",
"path": ""
},
"type": "hippogallerypicker:imagelink"
}
},
"role": "Owner"
},
{
"_links": {
"self": {
"href": "http://localhost:8080/site/api/documents/b8f5eb45-7200-452a-b26e-3118a0dc60b8"
}
},
"_meta": {
"id": "b8f5eb45-7200-452a-b26e-3118a0dc60b8",
"locale": "en",
"name": "breakfast",
"path": "events/2017/02/breakfast",
"type": "hippoaddoncontenthalapidemo:eventsdocument"
},
"content": {
"_meta": {
"type": "hippostd:html"
},
"content": "\n\n <p>Breakfast is served starting from 8:00 until 9:30.</p>\n\n \n"
},
"date": 1384239600000,
"enddate": 1518621060000,
"image": {
"_meta": {
"mirror": {
"id": "c8f03498-56eb-46c9-83b2-cf014f2e03d7",
"path": "content/gallery/hippoaddoncontenthalapidemo/samples/coffee-206142_150.jpg"
},
"type": "hippogallerypicker:imagelink"
}
},
"introduction": "Start the day with a nice breakfast.",
"location": "Room 101",
"title": "Breakfast"
},
{
"_links": {
"self": {
"href": "http://localhost:8080/site/api/documents/18e36c35-429d-4fee-b76e-eeabcbfc08bb"
}
},
"_meta": {
"id": "18e36c35-429d-4fee-b76e-eeabcbfc08bb",
"locale": "en",
"name": "introduction-speech",
"path": "events/2017/02/introduction-speech",
"type": "hippoaddoncontenthalapidemo:eventsdocument"
},
"content": {
"_meta": {
"type": "hippostd:html"
},
"content": "\n\n <p>Speech will be about the workshop.</p>\n\n \n"
},
"date": 1384246800000,
"enddate": 1518621060000,
"image": {
"_meta": {
"mirror": {
"id": "9f32434e-84e3-4150-a6f2-d89a67be2fb1",
"path": "content/gallery/hippoaddoncontenthalapidemo/samples/blue-199261_150.jpg"
},
"type": "hippogallerypicker:imagelink"
}
},
"introduction": "After breakfast there will be an introductory speech.",
"location": "Room 400",
"title": "Introduction speech"
},
{
"_links": {
"self": {
"href": "http://localhost:8080/site/api/documents/7a29ec60-2689-48b2-aca2-49696c5c23eb"
}
},
"_meta": {
"id": "7a29ec60-2689-48b2-aca2-49696c5c23eb",
"locale": "en",
"name": "workshop",
"path": "events/2017/02/workshop",
"type": "hippoaddoncontenthalapidemo:eventsdocument"
},
"content": {
"_meta": {
"type": "hippostd:html"
},
"content": "\n <strong>Everybody </strong>\n <p>can join the workshop and start practicing what they learned during the last\n week.</p>\n\n \n"
},
"date": 1384257600000,
"enddate": 1518621060000,
"image": {
"_meta": {
"mirror": {
"id": "d035387b-f9ce-49f6-bcb0-9ab6915a2d5f",
"path": "content/gallery/hippoaddoncontenthalapidemo/samples/pencils-199883_150.jpg"
},
"type": "hippogallerypicker:imagelink"
}
},
"introduction": "Workshop starts at 1:00",
"location": "Room 600",
"title": "Workshop"
},
// ...
]
},
"_meta": {
"limit": 10,
"offset": 0,
"size": 10,
"totalSize": 13
}
}
You can add query parameters like "_fields=title,introduction" only to include those two fields in the result (as well as metadata) like the following example:
http://localhost:8080/site/api/documents/?_fields=title,introduction
You can execute a full text search query by adding _q query parameter. So the following example will return only documents that contain 'medusa' text.
http://localhost:8080/site/api/documents/?_fields=title,introduction&_q==medusa
You can also add a new query parameter to sort documents by title (ascending) and date (descending).
http://localhost:8080/site/api/documents/?_fields=title,introduction&_sort=title,-date
You can get the second page only by adding _offset and _limit query parameters:
http://localhost:8080/site/api/documents/?_fields=title,introduction&_sort=title,-date&_offset=10&_limit=10
See the "Content HAL API URL Patterns" section in the Content HAL API Add-on Introduction page for more details on the supported query parameters.
In the following sections, the variations with the supported query parameters are ommitted for simplicity.
Also, see https://httpie.org/doc#querystring-parameters for more details on how to add query parameters in HTTPie commands.
Retrieving Collection of Documents in a Specific Type
You can specify a document type name to narrow the search result into the specific document types. For example, a request on http://localhost:8080/site/api/newsdocument/ will return a collection of news documents only:
$ http http://localhost:8080/site/api/newsdocument/
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Date: Tue, 29 Aug 2017 01:44:42 GMT
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
{
"_embedded": {
"documents": [
{
"_links": {
"self": {
"href": "http://localhost:8080/site/api/newsdocument/aeda2bcd-b21d-4ead-a2e6-c64a2ca051c8"
}
},
"_meta": {
"id": "aeda2bcd-b21d-4ead-a2e6-c64a2ca051c8",
"locale": "en",
"name": "the-gastropoda-news",
"path": "news/2017/02/the-gastropoda-news",
"type": "hippoaddoncontenthalapidemo:newsdocument"
},
"author": "Alfred Anonymous",
"content": {
"_meta": {
"type": "hippostd:html"
},
"content": "<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua...</p>"
},
"date": 1487085120000,
"image": {
"_meta": {
"mirror": {
"id": "3c740fcf-8ec5-4f00-a713-ff96caa645c8",
"path": "content/gallery/hippoaddoncontenthalapidemo/samples/snail-193611_640.jpg"
},
"type": "hippogallerypicker:imagelink"
}
},
"introduction": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua...",
"location": "Liverpool",
"source": "",
"title": "The gastropoda news"
},
// ...
{
"_links": {
"self": {
"href": "http://localhost:8080/site/api/newsdocument/c580ac64-3874-4717-a6d9-e5ad72080abe"
}
},
"_meta": {
"id": "c580ac64-3874-4717-a6d9-e5ad72080abe",
"locale": "en",
"name": "the-medusa-news",
"path": "news/2017/02/the-medusa-news",
"type": "hippoaddoncontenthalapidemo:newsdocument"
},
"author": "Alfred Anonymous",
"content": {
"_meta": {
"type": "hippostd:html"
},
"content": "<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua...</p>"
},
"date": 1487085120000,
"image": {
"_meta": {
"mirror": {
"id": "4709f797-61ae-4c36-93d4-63b5d50fc200",
"path": "content/gallery/hippoaddoncontenthalapidemo/samples/animal-2883_640.jpg"
},
"type": "hippogallerypicker:imagelink"
}
},
"introduction": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua...",
"location": "Rotterdam",
"source": "",
"title": "The medusa news"
}
]
},
"_meta": {
"limit": 10,
"offset": 0,
"size": 3,
"totalSize": 3
}
}
Retrieving Single Document
You can read single document content by specifying either UUID or releative path with the following example URLs:
- http://localhost:8080/site/api/newsdocument/aeda2bcd-b21d-4ead-a2e6-c64a2ca051c8
- http://localhost:8080/site/api/newsdocument/news/2017/02/the-gastropoda-news
- http://localhost:8080/site/api/documents/aeda2bcd-b21d-4ead-a2e6-c64a2ca051c8
- http://localhost:8080/site/api/documents/news/2017/02/the-gastropoda-news
An example output looks like this with the first URL example:
$ http http://localhost:8080/site/api/newsdocument/aeda2bcd-b21d-4ead-a2e6-c64a2ca051c8
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Date: Tue, 29 Aug 2017 01:50:49 GMT
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
{
"_links": {
"self": {
"href": "http://localhost:8080/site/api/newsdocument/aeda2bcd-b21d-4ead-a2e6-c64a2ca051c8"
}
},
"_meta": {
"id": "aeda2bcd-b21d-4ead-a2e6-c64a2ca051c8",
"locale": "en",
"name": "the-gastropoda-news",
"path": "news/2017/02/the-gastropoda-news",
"type": "hippoaddoncontenthalapidemo:newsdocument"
},
"author": "Alfred Anonymous",
"content": {
"_meta": {
"type": "hippostd:html"
},
"content": "<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua...</p>"
},
"date": 1487085120000,
"image": {
"_meta": {
"mirror": {
"id": "3c740fcf-8ec5-4f00-a713-ff96caa645c8",
"path": "content/gallery/hippoaddoncontenthalapidemo/samples/snail-193611_640.jpg"
},
"type": "hippogallerypicker:imagelink"
}
},
"introduction": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua...",
"location": "Liverpool",
"source": "",
"title": "The gastropoda news"
}
Retrieving All Resource Bundles
Here's an example command to retrieve all the available resource bundles:
$ http http://localhost:8080/site/api/resourcebundles/
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Date: Tue, 29 Aug 2017 02:16:25 GMT
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
{
"_embedded": {
"documents": [
{
"_links": {
"self": {
"href": "http://localhost:8080/site/api/resourcebundles/essentials.blog"
}
},
"_meta": {
"id": "2346b2b4-de7c-4d79-9bd2-e6ee97584640",
"name": "blog",
"path": "content/documents/administration/labels/blog",
"type": "resourcebundle:resourcebundle"
},
"basename": "essentials.blog",
"locales": []
},
{
"_links": {
"self": {
"href": "http://localhost:8080/site/api/resourcebundles/essentials.global"
}
},
"_meta": {
"id": "512ca079-2939-4b38-8266-ff59c8807a24",
"name": "global",
"path": "content/documents/administration/labels/global",
"type": "resourcebundle:resourcebundle"
},
"basename": "essentials.global",
"locales": []
},
//...
]
},
"_meta": {
"limit": 10,
"offset": 0,
"size": 6,
"totalSize": 6
}
}
Retrieving Folders
You can query all the folders:
$ http http://localhost:8080/site/api/folders/
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Date: Tue, 29 Aug 2017 02:21:19 GMT
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
{
"_embedded": {
"folders": [
{
"_links": {
"self": {
"href": "http://localhost:8080/site/api/folders/9ee59328-2f14-466b-bb49-e575eab36c6c"
}
},
"_meta": {
"id": "9ee59328-2f14-466b-bb49-e575eab36c6c",
"locale": "en",
"name": "banners",
"path": "banners",
"type": "hippostd:folder"
}
},
{
"_links": {
"self": {
"href": "http://localhost:8080/site/api/folders/e39779ae-586c-438b-a6ce-685a21581b48"
}
},
"_meta": {
"id": "e39779ae-586c-438b-a6ce-685a21581b48",
"locale": "en",
"name": "2017",
"path": "blog/2017",
"type": "hippostd:folder"
}
},
{
"_links": {
"self": {
"href": "http://localhost:8080/site/api/folders/c3e1d0fd-d32a-4bc8-ae51-a42a935fe47c"
}
},
"_meta": {
"id": "c3e1d0fd-d32a-4bc8-ae51-a42a935fe47c",
"locale": "en",
"name": "02",
"path": "blog/2017/02",
"type": "hippostd:folder"
}
},
{
"_links": {
"self": {
"href": "http://localhost:8080/site/api/folders/75a410a9-c350-461d-973c-ad016f95c2c3"
}
},
"_meta": {
"id": "75a410a9-c350-461d-973c-ad016f95c2c3",
"locale": "en",
"name": "blog",
"path": "blog",
"type": "hippostd:folder"
}
},
//...
]
},
"_meta": {
"limit": 10,
"offset": 0,
"size": 10,
"totalSize": 12
}
}
Retrieving Single Folder
You can specify either UUID or relative path of the folder to retrieve that specific folder content only. For example, the following URLs can return the same data since one refers to the folder by UUID and the other by relative path:
- http://localhost:8080/site/api/folders/e39779ae-586c-438b-a6ce-685a21581b48
- http://localhost:8080/site/api/folders/blog/2017
$ http http://localhost:8080/site/api/folders/e39779ae-586c-438b-a6ce-685a21581b48
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Date: Tue, 29 Aug 2017 02:28:06 GMT
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
{
"_embedded": {
"documents": [],
"folders": [
{
"_links": {
"self": {
"href": "http://localhost:8080/site/api/folders/c3e1d0fd-d32a-4bc8-ae51-a42a935fe47c"
}
},
"_meta": {
"id": "c3e1d0fd-d32a-4bc8-ae51-a42a935fe47c",
"locale": "en",
"name": "02",
"path": "02",
"type": "hippostd:folder"
}
}
]
},
"_links": {
"self": {
"href": "http://localhost:8080/site/api/folders/e39779ae-586c-438b-a6ce-685a21581b48"
}
},
"_meta": {
"id": "e39779ae-586c-438b-a6ce-685a21581b48",
"locale": "en",
"name": "2017",
"path": "blog/2017",
"type": "hippostd:folder"
}
}
$ http http://localhost:8080/site/api/folders/blog/2017
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Date: Tue, 29 Aug 2017 02:29:25 GMT
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
{
"_embedded": {
"documents": [],
"folders": [
{
"_links": {
"self": {
"href": "http://localhost:8080/site/api/folders/c3e1d0fd-d32a-4bc8-ae51-a42a935fe47c"
}
},
"_meta": {
"id": "c3e1d0fd-d32a-4bc8-ae51-a42a935fe47c",
"locale": "en",
"name": "02",
"path": "02",
"type": "hippostd:folder"
}
}
]
},
"_links": {
"self": {
"href": "http://localhost:8080/site/api/folders/e39779ae-586c-438b-a6ce-685a21581b48"
}
},
"_meta": {
"id": "e39779ae-586c-438b-a6ce-685a21581b48",
"locale": "en",
"name": "2017",
"path": "blog/2017",
"type": "hippostd:folder"
}
}
Retrieving Single Resource Bundle
You can retrieve single Resource Bundle:
$ http http://localhost:8080/site/api/resourcebundles/essentials.blog
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Date: Tue, 29 Aug 2017 02:20:20 GMT
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
{
"_links": {
"self": {
"href": "http://localhost:8080/site/api/resourcebundles/essentials.blog"
}
},
"basename": "essentials.blog",
"bundles": {
"default": {
"blog.moreby": "More by",
"blog.notfound": "No other posts found."
}
}
}
Retrieving Single Taxonomy Tree
You can retrieve single Taxonomy Tree:
$ http http://localhost:8080/site/api/taxonomies/exampletaxonomy
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Date: Tue, 29 Aug 2018 02:20:20 GMT
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
{
"name": "exampletaxonomy",
"locales": [
"en",
"en_GB",
"nl"
],
"categories": [
{
"key": "level-1",
"name": "level-1",
"path": "level-1",
"infos": {
"en": {
"name": "Level 1",
"description": null,
"synonyms": [],
"properties": {
"hippotaxonomy:name": "Level 1"
}
}
},
"categories": [
{
"key": "level-2-key",
"name": "level-2",
"path": "level-1/level-2",
"infos": {
"en": {
"name": "Level 2",
"description": null,
"synonyms": [],
"properties": {
"hippotaxonomy:name": "Level 2"
}
}
},
"categories": [
{
"key": "level-3",
"name": "level-3",
"path": "level-1/level-2/level-3",
"infos": {
"en": {
"name": "Level 3",
"description": null,
"synonyms": [],
"properties": {
"hippotaxonomy:name": "Level 3"
}
}
},
"categories": [
{
"key": "level-4",
"name": "level-4",
"path": "level-1/level-2/level-3/level-4",
"infos": {
"en": {
"name": "Level 4",
"description": null,
"synonyms": [],
"properties": {
"hippotaxonomy:name": "Level 4"
}
}
},
"categories": []
}
]
}
]
}
]
}
]
}