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
• Filtering by node type
• Free-text querying

These three 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.

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".

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"
      }
    },
    {
      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"
      }
    },
    {
      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"
      }
    },
    {
      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"
      }
    },
    {
      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"
      }
    },
    {
      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"
      }
    }
  ]
}

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