Document collection resource

The document collection resource lists all documents that are published and are 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

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

The resource has several mechanisms to control the output:

• Pagination
• Sorting
• Filtering by node type
• Free-text querying
• Document attributes selection

These mechanisms can be combined freely to construct more complex queries.

Pagination

The document collection resource by default returns the first 100 results. In case there are more documents available, or in case you want to have a smaller result set, the following query parameters can be used:

• _offset: number equals to or greater than 0 (default: 0)
• _max: number greater than 0 and lower or equal to 100 (default: 100)

For example, when there are 35 results, accessing the following:

http://localhost:8080/site/api/documents?_offset=10&_max=10

will return you results 11 through 20.

And accessing:

http://localhost:8080/site/api/documents?_offset=30&_max=10

will return you results 31 through 35.

Sorting

By default the result is ordered by the property hippostdpubwf:publicationDate, descending. But you can configure other properties to sort on as well.

parameter name	default value	description
_orderBy	hippostdpubwf:publicationDate	The property name on the JCR node to sort on. Multiple properties can be configured as well, separated with comma's. Please note: if sorting on a specific property is done, the result set will only contain documents that have that property.
_sortOrder	descending	Allowed values: ascending, descending, asc, desc. Multiple values can be configured comma-separated. When configuring multiple properties on the _orderBy parameter, the number of values on this parameter must be the same.

Example: http://localhost:8080/site/api/documents?_orderBy=newsdocument:title,newsdocument:date&_sortOrder=ascending,descending

Filtering by node type

The document collection resource by default exposes all published documents. It is possible to filter for instance so you get only News documents returned. To filter on node type, add the query parameter _nodetype

For example:

http://localhost:8080/site/api/documents?_nodetype=myhippoproject:newsdocument

will only return documents of type myhippoproject:newsdocument.

Free-text querying

It is possible to query using free-text queries using the query parameter _query

For example:

http://localhost:8080/site/api/documents?_query=news

will only return the 3 documents with the word “news” in it.

The query engine underneath the Content REST API allows you to pass in complex queries using multiple operators, parenthesis, etc. For example:

http://localhost:8080/site/api/documents?_query=news%20AND%20-medusa

should result in two documents: those that do contains “news” but do not contain “medusa”.

Technically, the query is executed using the JCR “contains” method. For details on the exact query capabilities, see the spec. Before handing the query over to JCR, the query is passed through SearchInputParsingUtils to prevent malicious queries. SearchInputParsingUtils also adds a bit of query syntax: it transforms queries such as "a AND NOT b" into "a AND -b".

Document attributes selection

By default, the response includes no document attributes (JCR properties). It is possible to include selected attributes using the query parameter _attributes.

For example:

http://localhost:8080/site/api/documents?_attributes=myhippoproject:title,myhippoproject:content

will include the attributes myhippoproject:title and myhippoproject:content for each document 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 workflow-related document attributes pubState, pubwfCreationDate, pubwfLastModificationDate, and pubwfPublicationDate.

Example

Below an example output of a project generated using Essentials after adding the News feature and the Events feature. Below the example are some notes about the formatting of the result body.

{
  "offset":0,
  "max":100,
  "count":6,
  "total":6,
  "more":false,
  "items":[
    {
      "name":"2013-harvest",
      "id":"30092f4e-2ef7-4c72-86a5-8ce895908937",
      "link":{
        "type":"local",
        "id":"30092f4e-2ef7-4c72-86a5-8ce895908937",
        "url":"http://localhost:8080/site/api/documents/30092f4e-2ef7-4c72-86a5-8ce895908937"
      },
      "type":"myhippoproject:newsdocument",
      "locale":"en"
    },
    {
      "name":"the-medusa-news",
      "id":"c580ac64-3874-4717-a6d9-e5ad72080abe",
      "link":{
        "type":"local",
        "id":"c580ac64-3874-4717-a6d9-e5ad72080abe",
        "url":"http://localhost:8080/site/api/documents/c580ac64-3874-4717-a6d9-e5ad72080abe"
      },
      "type":"myhippoproject:newsdocument",
      "locale":"en"
    },
    {
      "name":"the-gastropoda-news",
      "id":"aeda2bcd-b21d-4ead-a2e6-c64a2ca051c8",
      "link":{
        "type":"local",
        "id":"aeda2bcd-b21d-4ead-a2e6-c64a2ca051c8",
        "url":"http://localhost:8080/site/api/documents/aeda2bcd-b21d-4ead-a2e6-c64a2ca051c8"
      },
      "type":"myhippoproject:newsdocument",
      "locale":"en"
    },
    {
      "name":"breakfast",
      "id":"b8f5eb45-7200-452a-b26e-3118a0dc60b8",
      "link":{
        "type":"local",
        "id":"b8f5eb45-7200-452a-b26e-3118a0dc60b8",
        "url":"http://localhost:8080/site/api/documents/b8f5eb45-7200-452a-b26e-3118a0dc60b8"
      },
      "type":"myhippoproject:eventsdocument",
      "locale":"en"
    },
    {
      "name":"introduction-speech",
      "id":"18e36c35-429d-4fee-b76e-eeabcbfc08bb",
      "link":{
        "type":"local",
        "id":"18e36c35-429d-4fee-b76e-eeabcbfc08bb",
        "url":"http://localhost:8080/site/api/documents/18e36c35-429d-4fee-b76e-eeabcbfc08bb"
      },
      "type":"myhippoproject:eventsdocument",
      "locale":"en"
    },
    {
      "name":"workshop",
      "id":"7a29ec60-2689-48b2-aca2-49696c5c23eb",
      "link":{
        "type":"local",
        "id":"7a29ec60-2689-48b2-aca2-49696c5c23eb",
        "url":"http://localhost:8080/site/api/documents/7a29ec60-2689-48b2-aca2-49696c5c23eb"
      },
      "type":"myhippoproject:eventsdocument",
      "locale":"en"
    }
  ]
}

Notes:

• in case there are no results, items is an empty array
• offset: the specified offset, default = 0
• max: the max number of results, default = 100
• count: the number of results in this response, never more than max
• total: the total number of results in the content repository
• more: whether there are more results, so you can easily do a while loop if you want to fetch all results