Document Collection Resource

The document collection resource provides a list of all published documents that are descendants of the configured mount path.

After you run the REST setup tool and add the generic resources with default settings, the resource is available at:

http://localhost:8080/site/api/documents

This page includes example output and notes on the response format.

You can control the output of this resource using the following mechanisms:

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

You can combine these mechanisms to build complex queries.

Pagination

By default, the document collection resource returns the first 100 results. To retrieve additional documents or adjust the page size, use the following query parameters:

_offset: Integer, 0 or greater. Default is 0.
_max: Integer, greater than 0 and less than or equal to 100. Default is 100.

For example, if there are 35 results:

Accessing
http://localhost:8080/site/api/documents?_offset=10&_max=10
returns results 11 through 20.
Accessing
http://localhost:8080/site/api/documents?_offset=30&_max=10
returns results 31 through 35.

Sorting

Results are sorted by the hippostdpubwf:publicationDate property in descending order by default. You can sort by other properties using query parameters.

Parameter	Default value	Description
`_orderBy`	`hippostdpubwf:publicationDate`	Property name on the JCR node to sort by. You can specify multiple properties, separated by commas. Note: When sorting by a property, only documents that contain that property are included in the result set.
`_sortOrder`	`descending`	Allowed values: `ascending`, `descending`, `asc`, `desc`. You can specify multiple values, comma-separated. If you specify multiple properties in `_orderBy`, provide the same number of sort orders in `_sortOrder`.

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

Filtering by Node Type

By default, the resource exposes all published documents. To filter by node type, use the _nodetype query parameter.

For example:

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

returns only documents of type myproject:newsdocument.

Free-Text Querying

You can perform free-text searches using the _query parameter.

For example:

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

returns documents containing the word “news”.

Note: The examples in this section assume the “News” and “Events” features are present in the project.

The Content REST API supports complex queries with operators and parentheses. For example:

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

returns documents containing “news” but not “medusa”.

The API executes the query using the JCR contains method. For details on query capabilities, see the JCR specification. Before the query is sent to JCR, it is processed by SearchInputParsingUtils to prevent malicious input and to support syntax such as transforming "a AND NOT b" into "a AND -b".

Document Attribute Selection

By default, the response does not include document attributes (JCR properties). To include specific attributes, use the _attributes query parameter.

For example:

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

includes the myproject:title and myproject:content attributes for each document in the response. All other attributes are excluded. This applies to all attributes defined in the document type and to workflow-related attributes: pubState, pubwfCreationDate, pubwfLastModificationDate, and pubwfPublicationDate.

Example

The following example shows a response from a project generated with Essentials after adding the News and Events features.

{
  "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":"myproject: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":"myproject: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":"myproject: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":"myproject: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":"myproject: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":"myproject:eventsdocument",
      "locale":"en"
    }
  ]
}

Notes on the response format:

If there are no results, items is an empty array.
offset: The specified offset. Default is 0.
max: The maximum number of results. Default is 100.
count: The number of results in this response. Never exceeds max.
total: The total number of results in the content repository.
more: Indicates whether more results are available. Use this to implement pagination if you need to retrieve all results.