Technical Preview: Retrieve a list of content in folder for QD

Added by

Rui BJ Yang | Edited by IBM contributor

Rui BJ Yang on March 20, 2011 | Version 8

Abstract

No abstract provided.

Tags: Folder API, Quickr Domino8.5

ShowTable of Contents

HideTable of Contents

1 Retrieve a list of content in folder
2 URL endpoints
3 Authentication
4 Arguments
5 Error Codes
6 Example Request for Quickr Domino8.5
7 Example Response for Quickr Domino8.5
8 Response tag

Retrieve a list of content in folder

This is the specification for applications that retrieve lists of resources contained by a Folder.

URL endpoints

Perform a GET operation on one of the following URL formats:

URL	Description
/library/{library-id}/folder/{folder-id}/feed	Retrieve resources contained by a folder given its id

Authentication

This method does not require authentication to retrieve public resources. If authentication is provided, the user must have 'View' authority on the specified resource.

Arguments

The following HTTP headers maybe supported for this operation.

Header	Description
If-Modified-Since	Used to validate local cache of result. If no change is found, return HTTP response code 304 (Not Modified).
If-None-Match	Contains ETag response header sent by the server in a previous request to the same url. If the ETag is still valid for the specified resource, HTTP response code 304 (Not Modified) is returned.

The following URL arguments are supported on this operation. The default value for any argument is marked as bold in the table below.

Argument	Values	Description
pagesize	number (10,20, etc.)	Specifies number of items to include in a paged request
page	number (1, 2, 3, etc.)	Specifies page to be retrieved assuming constant page size
sK	string (title, created, updated, published, modified, desc, downloaded)	value to sort the response
sO	string (asc, dsc)	Specifies the order of the sort as either ascending or descending
sI	number (1, 5, 10, etc.)	Specifies the start index in the collection from which the results should be returned. Ignored if page is provided
acls	boolean (true, false)	Specifies if the authenticated users permissions are returned each library
category	string (folder, document, draft)	comma-delimited list of resource types to include in the response.
includeLocked	boolean (true, false)	if true, adds an entry extension <td:locked showing if document is locked
includeLockOwner	boolean true, false)	if true, adds an entry extension <td:lockOwner showing who holds the lock

If callers specify a category filter of type draft, all other filter types are ignored and only content of type draft is returned.

Error Codes

Error Code	Description
Unknown	Returned when the cause of an error is unknown
AccessDenied	Returned when the cause of an error is due to a permission restriction
ItemNotFound	Returned when the cause of an error is related to a resource not being found
UnsupportedOperation	Returned when the operation is not supported
ColNotSortable	Returned when the default sort column is no longer sortable

Example Request for Quickr Domino8.5

The request is to get a folder with acl feed in which there are one folder with acl and one document.

GET dm/atom/library/%5B@Pplace2/@RMain.nsf%5D/folder/%5B@Pplace2/@RMain.nsf/@Fh_4EC8CD8D315A961E48257853002BB7C5%5D/feed?

acls=true&psmd=48257855002A8359&noAuthHeader=true HTTP/1.1

Example Response for Quickr Domino8.5

The response is returned with two entries.

<?xml version="1.0" encoding="utf-8" ?>

<feed xml:base="http://yr.cn.ibm.com/" xmlns="http://www.w3.org/2005/Atom" xmlns:td="urn:ibm.com/td" xmlns:snx="http://www.ibm.com/xmlns/prod/sn">

  <title type="text">folder1</title>

  <updated>2011-03-16T07:44:37Z</updated>

  <created>2011-03-14T07:57:30Z</created>

  <author>

    <name>Testuser7</name>

    <uri>CN=Testuser7%2FO=Notesdev%2FC=US</uri>

    <email>Testuser7@us.ibm.com</email>

  </author>

  <id>urn:lsid:ibm:com:td:_Pplace2_RMain_F4EC8CD8D315A961E48257853002BB7C5</id>

  <td:uuid>_Pplace2_RMain_F4EC8CD8D315A961E48257853002BB7C5</td:uuid>

  <link href="dm/atom/library/_Pplace2_RMain/folder/_Pplace2_RMain_F4EC8CD8D315A961E48257853002BB7C5/feed" rel="self"/>

  <link href="LotusQuickr/place2/Main.nsf/h_Toc/C225E6D43B70759D48257853002BB7B5?OpenDocument" rel="alternate"/>

  <generator uri="LotusQuickr/place2/Main.nsf/h_Toc/C225E6D43B70759D48257853002BB7B5?OpenDocument"  version="851003.002" >LotusQuickr</generator>

  <serverdate>2011-03-16T07:52:43Z</serverdate>

  <td:psmd newdata="1">48257855002A8A32</td:psmd>

  <entry xmlns:td="urn:ibm.com/td">

    <id>urn:lsid:ibm:com:td:_Pplace2_RMain_FBF096C7BE65127CE48257855002A80ED</id>

    <td:uuid>_Pplace2_RMain_FBF096C7BE65127CE48257855002A80ED</td:uuid>

    <link href="dm/atom/library/_Pplace2_RMain/folder/_Pplace2_RMain_FBF096C7BE65127CE48257855002A80ED/entry" rel="self"/>

    <link href="LotusQuickr/place2/Main.nsf/h_Toc/77FCB4C1FED653C748257855002A80D6?OpenDocument" rel="alternate"/>

    <link href="dm/atom/library/_Pplace2_RMain/folder/_Pplace2_RMain_FBF096C7BE65127CE48257855002A80ED/feed" rel="current"/>

    <link href="dm/atom/library/_Pplace2_RMain/folder/_Pplace2_RMain_FBF096C7BE65127CE48257855002A80ED/entry" rel="edit"/>

    <content  type="application/atom+xml"  src="dm/atom/library/_Pplace2_RMain/folder/_Pplace2_RMain_FBF096C7BE65127CE48257855002A80ED/feed" />

    <link href="dm/atom/library/_Pplace2_RMain.nsf/view/_Pplace2_RMain.nsf_F4EC8CD8D315A961E48257853002BB7C5/feed" rel="parent"/>

    <td:type>simplelist</td:type>

    <category  term="folder"  scheme="tag:ibm.com,2006:td/type"  label="folder" />

    <title type="text">folder with acl</title>

    <summary type="text">

      <![CDATA[]]>

      </summary>

    <published>2011-03-16T07:44:38Z</published>

    <updated>2011-03-16T07:44:38Z</updated>

    <author>

      <name>Testuser7</name>

      <uri>CN=Testuser7/O=Notesdev/C=US</uri>

      <email>Testuser7@us.ibm.com</email>

    </author>

    <td:created>2011-03-16T07:44:14Z</td:created>

    <td:modified>2011-03-16T07:44:38Z</td:modified>

    <td:documenttype>1</td:documenttype>

    <td:modifier>

      <td:name>Testuser7</td:name>

      <td:uri>CN=Testuser7/O=Notesdev/C=US</td:uri>

      <td:email>Testuser7@us.ibm.com</td:email>

    </td:modifier>

    <td:depth>0</td:depth>

  </entry>

  <entry xmlns:td="urn:ibm.com/td">

    <id>urn:lsid:ibm:com:td:_Pplace2_RMain_D460616A85D04A06C48257855002A5984_Aupload_201_20attach.txt</id>

    <td:uuid>_Pplace2_RMain_D460616A85D04A06C48257855002A5984_Aupload_201_20attach.txt</td:uuid>

    <link href="dm/atom/library/_Pplace2_RMain/document/_Pplace2_RMain_D460616A85D04A06C48257855002A5984_Aupload_201_20attach.txt/

entry" rel="self"/>

    <link href="LotusQuickr/place2/Main.nsf/4EC8CD8D315A961E48257853002BB7C5/460616A85D04A06C48257855002A5984/?OpenDocument" rel="alternate"/>

    <link href="dm/atom/library/_Pplace2_RMain/document/_Pplace2_RMain_D460616A85D04A06C48257855002A5984_Aupload_201_20attach.txt/

feed" rel="current"/>

    <link href="dm/atom/library/_Pplace2_RMain/document/_Pplace2_RMain_D460616A85D04A06C48257855002A5984_Aupload_201_20attach.txt/

entry" rel="edit"/>

    <content  type="application/atom+xml"  src="dm/atom/library/_Pplace2_RMain/document/_Pplace2_RMain_D460616A85D04A06C48257855002A5984_Aupload_201_20attach.txt/feed" />

    <link href="dm/atom/library/_Pplace2_RMain/document/_Pplace2_RMain_D460616A85D04A06C48257855002A5984_Aupload_201_20attach.txt/

media" type="text/plain" title="upload 1 attach.txt" length="50" rel="edit-media"/>

    <link href="dm/atom/library/_Pplace2_RMain/document/_Pplace2_RMain_D460616A85D04A06C48257855002A5984_Aupload_201_20attach.txt/

media" type="text/plain" title="upload 1 attach.txt" length="50" rel="enclosure"/>

    <link href="dm/atom/library/_Pplace2_RMain/document/_Pplace2_RMain_D460616A85D04A06C48257855002A5984_Aupload_201_20attach.txt/

media" type="text/plain" title="upload 1 attach.txt" length="50" rel="attachment0"/>

    <category  term="document"  scheme="tag:ibm.com,2006:td/type"  label="document" />

    <title type="text">upload 1 attach</title>

    <summary type="text">

      <![CDATA[]]>

      </summary>

    <published>2011-03-16T07:42:34Z</published>

    <updated>2011-03-16T07:42:34Z</updated>

    <author>

      <name>Testuser7</name>

      <uri>CN=Testuser7/O=Notesdev/C=US</uri>

      <email>Testuser7@us.ibm.com</email>

    </author>

    <td:created>2011-03-16T07:42:34Z</td:created>

    <td:modified>2011-03-16T07:42:34Z</td:modified>

    <td:documenttype>94913AFBEAB46DA8052576A1006611BC</td:documenttype>

    <td:modifier>

      <td:name>Testuser7</td:name>

      <td:uri>CN=Testuser7/O=Notesdev/C=US</td:uri>

      <td:email>Testuser7@us.ibm.com</td:email>

    </td:modifier>

    <td:responseCount>0</td:responseCount>

    <td:depth>0</td:depth>

  </entry>

  <td:totalNumber>2</td:totalNumber>

  <td:acls inherit="false">

    <td:manager></td:manager>

    <td:contributor>

      <td:person>

        <uri>CN=domino testuser10/O=notesdev/C=US</uri>

        <td:dn>CN=domino testuser10,O=notesdev,C=US</td:dn>

        <name>domino testuser10</name>

      </td:person>

      <td:person>

        <uri>CN=domino testuser9/O=notesdev/C=US</uri>

        <td:dn>CN=domino testuser9,O=notesdev,C=US</td:dn>

        <name>domino testuser9</name>

      </td:person>

    </td:contributor>

    <td:reader></td:reader>

  </td:acls>

  <td:role>manager</td:role>

  <td:permissions>AddChild,AddFolder,Delete,EditProperties,Edit,View,GrantAccess,GrantAccessView,GrantAccessEdit</td:permissions>

  <link href="dm/atom/library/_Pplace2_RMain/folder/_Pplace2_RMain_F4EC8CD8D315A961E48257853002BB7C5/feed?pageSize=10" rel="first"/>

</feed>

Response tag

Tag	Required	Description
link rel="self"	Y	Identifies a resource equivalent to the containing element. as defined in Atom spec.
link rel= "alternate"	Y	Identifies an alternate version of the resource described by the containing element. as defined in Atom spec.
link rel= "edit"	N	Identifies the resource that is editable.
link rel= "parent"	N	Points to the parent page, parent folder or parent place.
link rel= "attachmentX"	N	If a page/document/draft has one or more than one attachments,the attachmentX(X starts from 0) url will represent the attachment itself.
link rel= "edit-media"	N	"edit-media" link accompanies "attachmentX" link. It points to the attachment itself for edit.
link rel= "current"	N	The current link points to the document/page feed itself.
link rel= "enclosure"	N	The link points to document's attachment, or page feed.
id	Y	unique identifier of a resource, as defined in Atom spec
author	Y	The feed author or entry author, the one who creates the resource. If the resource is systemic, the author field could be blank
title	Y	The title of feed or entry
published	N	The last modified date of entry
updated	N	The last modified date of feed or entry
summary	Y	The abstract of feed or entry
td:created	Y	The created date of entry
td:modified	Y	The modified date of entry
td:modifier	Y	The last editor of the entry
category	Y	It indicates entry type, including page/document/draft/draftpage/folder.
content	N	The link points to document's attachment, or page feed.
td:lockOwner	N	The user who holds the lock on the resource
td:uuid	Y	unique identifier of a resource
td:label	N	Relative file system mapped label, mostly the same value as title.
td:acls	N	ACL of the folder or the document. Returned by folder or document entry.
td:totalNumber	N	Total number of Entries in a Feed.
generator	Y	identifies the agent used to generate a feed, for debugging and other purposes. as defined in Atom spec.
serverdate	Y	Date of server.
td:documenttype	N	document type for this resource.
source	N	allow the aggregation of entries from different feeds while retaining information about an entry's source feed. as defined in Atom spec.
td:psmd	N	time stamp.
td:responseCount	N	The number of document/page's comment
td:role	N	Current user's acl role of the specific folder or document. For example, when a folder editor logs in the place and get the folder entry, it will be td:editor in td:role.
td:permissions	N	Permission of current role. In 8.5, Folder reader's permission: View; Folder editor's permission: AddChild,Edit,View Folder contributor's permission: AddChild,View Folder manager's permission: AddChild, AddFolder, Delete, EditProperties, Edit, View, GrantAccess, GrantAccessView, GrantAccessEdit
td:depth	N	If the entry is returned from a view feed, this value shows how much the document is indented in this view (used for showing responses accordingly)
td:reader	N	An acl role. Folder reader. Document reader.
td:group	N	Stands for a group. Similar tag is . includes uri, and name.
td:person	N	Stands for a person. Similar tag is . includes uri, and name.
td:dn	N	Distinguished name of a person or a group.
name	Y	The display name of a person or a group.
td:contributor	N	An acl role. Folder author. Document author.
td:editor	N	An acl role. Folder editor.
td:manager	N	An acl role. Folder manager.
td:type	N	Specify folder type when creating folder. The type could be simple list, tabbed, slide show.
td:subtype	N	Only used for folder to differentiate different types of folders. Currently available values: h_List(list), h_Forum(forum). User can also provide customized value when create customized folder.