Example Request and Response Payloads

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

This page provides example request and response payloads for the built-in Content HAL APIs. All examples use HTTPie (http) to demonstrate API calls.

Retrieve a Collection of Documents

The following example retrieves a collection of documents from http://localhost:8080/site/api/documents/. The response embeds all documents in the documents property within 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
    }
}

To include only specific fields such as title and introduction in the response (along with metadata), use the _fields query parameter:

http://localhost:8080/site/api/documents/?_fields=title,introduction

To perform a full-text search, add the _q query parameter. The following example returns documents containing the text medusa:

http://localhost:8080/site/api/documents/?_fields=title,introduction&_q==medusa

To sort documents by title (ascending) and date (descending), use the _sort parameter:

http://localhost:8080/site/api/documents/?_fields=title,introduction&_sort=title,-date

To retrieve the second page of results, use the _offset and _limit parameters:

http://localhost:8080/site/api/documents/?_fields=title,introduction&_sort=title,-date&_offset=10&_limit=10

For detailed information about supported query parameters, see the Content HAL API Add-on Introduction, specifically the "Content HAL API URL Patterns" section.

The following sections omit query parameter variations for clarity.

For more information about adding query parameters in HTTPie commands, refer to HTTPie documentation.

Retrieve Documents by Type

To limit results to a specific document type, specify the type in the URL. For example, to retrieve only news documents, use:

$ 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
    }
}

Retrieve a Single Document

To retrieve a single document, specify either the UUID or the relative path in the URL. The following URLs are valid:

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

The response for the first URL is shown below:

$ 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"
}

Retrieve All Resource Bundles

To retrieve all available resource bundles, use the following request:

$ 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
    }
}

Retrieve All Folders

To retrieve all folders, use the following request:

$ 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
    }
}

Retrieve a Single Folder

To retrieve a specific folder, provide either the UUID or the relative path. The following URLs return the same folder:

http://localhost:8080/site/api/folders/e39779ae-586c-438b-a6ce-685a21581b48
http://localhost:8080/site/api/folders/blog/2017

Example response:

$ 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"
    }
}

Retrieve a Single Resource Bundle

To retrieve a single resource bundle, use the following request:

$ 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