Bloomreach

Bloomreach Documentation version

Developer Docs / Frontend Integration / APIs / Content REST API / Document Detail Resource

Document detail resource

The document detail resource provides the details of a single published document. The document is selected using a UUID. Technically, this UUID must be the UUID of a handle of a published document which is a descendant of the configured mount path.

After running the REST setup tool and adding the generic resources using the default settings, this resource can be found in your local project at:

http://localhost:8080/site/api/documents/{uuid}

At the bottom of this document you find example output and some notes about the formatting of the result body.

The resource has three key capabilities that are described in more detail:

  • Link rewriting
  • Uses the Content Model to render output
  • Document attributes selection

Link rewriting

As part of the output, the resource applies link rewriting to all links in the content. The following rules are applied in order:

  • Links to images and assets are rendered as links that are served over the binaries servlet. Certain link pickers allow the selection of a specific image variant for a link; if such a specific variant is selected, a link to that variant is returned, else the link to the default variant is returned.
  • If the document is also exposed over the same mount, a link to that resource is generated.
  • If the document is exposed over a mount that is not a Content REST API (typically a regular web channel), a link to the page rendering that document is generated.
  • If the link is broken, or if the document is not exposed over any mount, a broken link is rendered in the output.

Note: if the document is exposed over a different mount, using the Content REST API, a link to that resource is not generated because cross mount linking to mounts without sitemap is not supported.

Uses the Content Model to render output

The document detail resource uses the Content Model to render its output. Only those document properties are rendered that are known to be part of the Content Model. The Content REST API uses the Content Type Service to query the Content Model.

As part of the release, the registration of all certified plugins has been verified to contain all necessary properties. If you plan to use the Content REST API in an existing project, and have developed custom plugins for the CMS, and you experience that not all content is exposed, this is likely caused by the fact that the plugin does not fully register all properties that are used.

Document attributes selection

By default, the response includes all of a document's attributes (JCR properties). It is possible to specify which attributes to include using the query parameter _attributes.

For example:

http://localhost:8080/site/api/documents/9caea793-42b1-4f3e-a8e5-d58f810ce2ef?_attributes=myproject:title,myproject:content

will only include the attributes myproject:title and myproject:content in the response. All other attributes will be excluded. This applies to all document attributes defined in the document's type as well as to the four workflow-related document attributes pubState, pubwfCreationDate, pubwfLastModificationDate, and pubwfPublicationDate.

Known limitations

Projects that have had several upgrades to their content model may benefit from running Groovy scripts to make the output of the Content REST API consistent. In case a project has added a non-mandatory property P, documents that were published before the introduction of P will not render the property at all, whereas documents that were created after the introduction of P will render an empty value. To make this consistent, a Groovy script can be executed that adds P and an empty value to documents where it is missing.

Binary properties are not rendered, use image sets or assets instead.

Example

Below an example output of the “The gastropoda news” document which is bootstrapped as part of the "News" feature in Essentials. The document was edited somewhat: a link and image have been added to the “Content” property.

{
  id: "aeda2bcd-b21d-4ead-a2e6-c64a2ca051c8",
  name: "the-gastropoda-news",
  displayName: "The gastropoda news",
  type: "myproject:newsdocument",
  locale: "en",
  pubState: "published",
  pubwfCreationDate: "2013-11-12T12:50:00.000+01:00",
  pubwfLastModificationDate: "2016-02-01T11:36:32.598+01:00",
  pubwfPublicationDate: "2016-02-01T11:36:34.780+01:00",
  items: {
    "myproject:source": "",
    "myproject:location": "Liverpool",
    "myproject:title": "The gastropoda news",
    "myproject:author": "Alfred Anonymous",
    "myproject:date": "2016-02-01T10:58:00.000+01:00",
    "myproject:introduction": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum",
    "myproject:content": {
      type: "hippostd:html",
      content: "<p><a data-hippo-link="the-medusa-news">Lorem</a> ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum</p> <p><img data-hippo-link="animal-2883_640.jpg" /></p> <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum&#160;</p> <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum&#160;</p>",
      links: {
        "the-medusa-news": {
          type: "local",
          id: "c580ac64-3874-4717-a6d9-e5ad72080abe",
          url: "http://localhost:8080/site/api/documents/c580ac64-3874-4717-a6d9-e5ad72080abe"
        },
        "animal-2883_640.jpg": {
          type: "binary",
          url: "http://localhost:8080/site/binaries/content/gallery/myproject/samples/animal-2883_640.jpg"
        }
      }
    },
    "myproject:image": {
      type: "hippogallerypicker:imagelink",
      link: {
        type: "binary",
        url: "http://localhost:8080/site/binaries/content/gallery/myproject/samples/snail-193611_640.jpg"
      }
    }
  }
}

Notes:
Links within rich text fields have a “data-hippo-link” attribute that links the HTML element with the details of the link in the “links” object.

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?