Getting a feed of the files in a folder
Added by IBM contributorIBM | Edited by Melissa M Mahoney on August 26, 2015
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

You can use the Files API with the GET method to retrieve a feed of files in a specific folder.
Note: {collection-id} is the value of the <td:uuid> element in the collection's Atom document.

Discoverability

You can derive the URL from the folders feed, such as My Folders. Find the entry representing the folder, and then get the value of the href attribute of the <link> element with the rel="files" attribute.

Request parameters

Use one or more of the input parameters to narrow the search. Separate multiple parameters with an ampersand (&).
 

Authentication

This method does not require authentication to retrieve public resources. If authentication is provided, the user must have View access on a collection. To test whether the current user can retrieve a list of items in a Collection, use the [Get list of members of a specific role of a Collection] to see if the user belongs to the Reader, Contributor or Manager Roles.

Input
Method URI Description
GET /files/{auth}/api/collection/{collection-id}/feed {collection-id} is the value of the <td:uuid> element in the collection's Atom document.
GET /files/{auth}/api/communitycollection/{community-id}/feed Retrieve a list of items in a community collection.
Name Type Optional Description
collection-id
string No {collection-id} is the value of the <td:uuid> element in the collection's Atom document.
auth
enumerated No The authorization protocol being used by your application to access Connections Cloud.
Authorized values:
  • basic
  • oauth
Name Type Optional Description
added
int Yes Long integer representing a timestamp. Returns all files that were added to the folder after the specified date and time.
addedBy
string Yes User ID. String. Specifies to return only file folders created by the user specified by the user ID.
created
int Yes Long integer representing a timestamp. Returns all files created after the specified date and time.
page
int Yes Page number. Specifies the page to be returned. The default value is 1, which returns the first page
pageSize
int Yes Page size. Specifies the number of entries to return per page. The default value is 10. The maximum value you can specify is 500.
Note: This parameter replaces the pageSize parameter. The pageSize parameter is supported for backwards compatibility only; it will be deprecated in a future release.
sl
int Yes Start index. Specifies the start index (number) in the folder from which the results should be returned. This parameter is ignored if a page parameter is provided.
sortBy
enumerated Yes String. Specifies what to sort the returned entries by. Options are:
created
Sorts the entries by the date the item was created.
modified
Sorts the entries by the last modified date.
published
Sorts the entries by the date the item was published (usually related to atom:published element).
title
Sorts the entries alphabetically by title. The title used is the text that is displayed in the <title> element of each entry in the feed.
updated
Sorts the entries by the last time the item was updated.
The default value of this parameter is modified.
Authorized values:
  • created
  • modified
  • published
  • title
  • updated
sortOrder
enumerated Yes Specifies the order in which to sort the results. The options are:
asc
Sorts the results in ascending order.
desc
Sorts the results in descending order.
If a value is specified for the sortBy parameter, but none is specified for this parameter, then this parameter defaults to asc. If neither is specified, this parameter defaults to desc.
Authorized values:
  • asc
  • desc
tag
string Yes String. Filters the returns by the specified tag. You can specify up to three tag parameters. Example: ?tag=tag1&tag=tag2
sC
enumerated Yes String. Specifies sort category. The default depends on the category argument and changes to 'collection' for category=collection.
The default value of this parameter is document.
Authorized values:
  • document
  • collection
  • all
category
enumerated Yes String. To filter the items by the specified item type. Options include:
document
Returns the selection of contained files
collection
Returns contained folders
Page
Returns wiki pages
all
Returns a combination of both (folders will be returned in front of files).
Authorized values:
  • document
  • collection
  • page
  • all
format
enumerated Yes String. Format the result should be returned as.
The default value is ATOM.
Authorized values:
  • ATOM
  • JSON
includeNotification
enumerated Yes String. If the notification information will be returned in collection entry.
Default value is false.
Authorized values:
  • true
  • false
type
enumerated Yes String. Filter on files that are in either personal or community libraries.
Default value is allFiles.
Authorized values:
  • allFiles
  • personalFiles
  • communityFiles
sharePermission
enumerated Yes String. Filter the files by shared permission into the collection.
Authorized values:
  • view
  • edit
includeFavorite
enumerated Yes String. Indicate whether to return favorite information of files in the feed.
The default value is false.
Authorized values:
  • false
  • true
label
string Yes String. Filter the files or sub-folders with the label of the folder.
title
string No String. Filter files and/or sub-folders based on their title. Parameters isExact and wildmatch define how the filter string matches a title. See wildmatch for details.
acIs
enumerated Yes String. Indicate whether to return permission information of files in the feed.
Default value is false.
Authorized values:
  • false
  • true
collectionAcIs
enumerated Yes String. Indicate whether to return permission information for the folder/community folder.
The default value is false.
Authorized values:
  • false
  • true
access
enumerated Yes String. For community collections only. Filter the content of the returned feed by the access role of the authenticated user.
Authorized values:
  • reader
  • editor
  • manager
includeAncestors
enumerated Yes String. Specify whether to return ancestors of the folder. If it is a top level folder, there will be no element in <td:ancestors>.
Authorized values:
  • true
  • false
isExact
enumerated Yes Boolean. Controls whether wildmatch is applied to title filter. When isExact=true then wildmatch is ignored and title filter matches only on exact match.
Default value is true if category=all or category=collection
Default value is false if category=document or category=page
Authorized values:
  • true
  • false
wildmatch
enumerated Yes String. Controls, together with isExact, how the title filter matches the title string of files or folders. There are three different matching modes for a title filter <f>:
1. When isExact=true then <f> matches only identical strings.
2. When isExact=false and wildmatch=prefix then <f> matches all strings starting with <f>.
3. When isExact=false and wildmatch=anywhere then <f> matches all strings that contain <f> at any position.
Default value is prefix.
Authorized values:
  • prefix
  • anywhere
Name Type Optional Description
Authorization
enumerated No The authentication mechanism selected by your application to access the API.
Basic is the Base64 encoding of the IBM Connections Cloud username and password: Base64(username:password). For example, Base64(twatson@us.ibm.com:password).
Bearer is the oauth 2.0 access token that is generated when the user grants your application access to IBM Connections Cloud services.
See the reference topic "OAuth 2.0 APIs for web server flow" for more information.
Authorized values:
  • bearer
  • basic
Output
Content Type: application/atom+xml
Code Description
200
OK. Indicates that the request was received successfully.
401
Unauthorized. Returned when no authenticated user or no userid, email, or key parameter are provided on the request.
500
Internal server error. The server encountered an unexpected condition that prevented it from fulfilling the request.
403
Forbidden. The server refuses to fulfill a request, typically because the request was for an object that you don't have permission to access.
404
Item Not Found. Returned when the resource was not found
Examples
Headers Argument "label" must be specified. Argument "category" should be specified as well, only support values: {document | collection}.
GET /files/basic/api/collection/26d7c8ac-a997-4fc1-b605-33a45591fe12/feed?label=testCheckLabelInCollection_file_cd6207d5-d57d-41b7-8b06-17b3d3c275b6  HTTP/1.1
or
GET /files/basic/api/collection/26d7c8ac-a997-4fc1-b605-33a45591fe12/feed?label=testCheckLabelInCollection_file_cd6207d5-d57d-41b7-8b06-17b3d3c275b6&category=document  HTTP/1.1
or
GET /files/basic/api/collection/26d7c8ac-a997-4fc1-b605-33a45591fe12/feed?category=collection&label=testCheckLabelInCollection_folder_3_0f45f4f0-8160-4459-913d-d434f7a6b04a  HTTP/1.1

Response returned by the server
<feed xmlns:td="urn:ibm.com/td" xmlns="http://www.w3.org/2005/Atom" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:snx="http://www.ibm.com/xmlns/prod/sn" xmlns:thr="http://purl.org/syndication/thread/1.0">
   <generator version="0.0.0.0" uri="http://www.ibm.com/xmlns/prod/sn">IBM Connections - Files</generator>
   <id>urn:lsid:ibm.com:td:26d7c8ac-a997-4fc1-b605-33a45591fe12</id>
   <link href="https://filesvm004.cn.ibm.com:9443/files/basic/api/collection/26d7c8ac-a997-4fc1-b605-33a45591fe12/feed" rel="self"></link>
   <link href="https://filesvm004.cn.ibm.com:9443/files/basic/api/collection/26d7c8ac-a997-4fc1-b605-33a45591fe12/entry" rel="edit"></link>
   <link href="https://filesvm004.cn.ibm.com:9443/files/app/folder/26d7c8ac-a997-4fc1-b605-33a45591fe12/" rel="alternate"></link>
   <title type="text">testCheckLabelInCollection_folder_1add02a4-f7c7-40c6-b776-e773c576bac9</title>
   <td:uuid xmlns:td="urn:ibm.com/td">26d7c8ac-a997-4fc1-b605-33a45591fe12</td:uuid>
   <td:type xmlns:td="urn:ibm.com/td">personal</td:type>
   <subtitle type="text">testCheckLabelInCollection_folder_1add02a4-f7c7-40c6-b776-e773c576bac9</subtitle>
   <author>
      <name>Liz Schonfeld</name>
      <snx:userid xmlns:snx="http://www.ibm.com/xmlns/prod/sn">lschonfeld</snx:userid>
      <email>lschonfeld@renovations.com</email>
      <snx:userState xmlns:snx="http://www.ibm.com/xmlns/prod/sn">active</snx:userState>
   </author>
   <td:modifier xmlns:td="urn:ibm.com/td">
      <name>Liz Schonfeld</name>
      <snx:userid xmlns:snx="http://www.ibm.com/xmlns/prod/sn">lschonfeld</snx:userid>
      <email>lschonfeld@renovations.com</email>
      <snx:userState xmlns:snx="http://www.ibm.com/xmlns/prod/sn">active</snx:userState>
   </td:modifier>
   <published>2015-07-28T05:01:31.834Z</published>
   <updated>2015-07-28T05:01:32.255Z</updated>
   <td:created xmlns:td="urn:ibm.com/td">2015-07-28T05:01:31.834Z</td:created>
   <td:modified xmlns:td="urn:ibm.com/td">2015-07-28T05:01:32.255Z</td:modified>
   <td:visibility xmlns:td="urn:ibm.com/td">public</td:visibility>
   <snx:isExternal xmlns:snx="http://www.ibm.com/xmlns/prod/sn">false</snx:isExternal>
   <snx:rank xmlns:snx="http://www.ibm.com/xmlns/prod/sn" scheme="http://www.ibm.com/xmlns/prod/sn/item">1</snx:rank>
   <snx:rank xmlns:snx="http://www.ibm.com/xmlns/prod/sn" scheme="http://www.ibm.com/xmlns/prod/sn/user">0</snx:rank>
   <snx:rank xmlns:snx="http://www.ibm.com/xmlns/prod/sn" scheme="http://www.ibm.com/xmlns/prod/sn/group">0</snx:rank>
   <opensearch:totalResults xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">1</opensearch:totalResults>
   <td:allowSetFavorite xmlns:td="urn:ibm.com/td">true</td:allowSetFavorite>
   <td:allowFollowing xmlns:td="urn:ibm.com/td">true</td:allowFollowing>
   <entry>
      <id>urn:lsid:ibm.com:td:aae1fad2-38dd-4167-8a40-a1ac677f0cc3</id>
      <title type="text">testCheckLabelInCollection_file_cd6207d5-d57d-41b7-8b06-17b3d3c275b6</title>
      <link href="https://filesvm004.cn.ibm.com:9443/files/basic/api/library/80869595-b7af-49e8-8ce6-870421a25b37/document/aae1fad2-38dd-4167-8a40-a1ac677f0cc3/entry" rel="self"></link>
      <link href="https://filesvm004.cn.ibm.com:9443/files/app/file/aae1fad2-38dd-4167-8a40-a1ac677f0cc3" rel="alternate" type="text/html"></link>
      <link href="https://filesvm004.cn.ibm.com:9443/files/basic/api/library/80869595-b7af-49e8-8ce6-870421a25b37/document/aae1fad2-38dd-4167-8a40-a1ac677f0cc3/entry" rel="edit"></link>
      <link href="https://filesvm004.cn.ibm.com:9443/files/basic/api/library/80869595-b7af-49e8-8ce6-870421a25b37/document/aae1fad2-38dd-4167-8a40-a1ac677f0cc3/media" rel="edit-media"></link>
      <link href="https://filesvm004.cn.ibm.com:9443/files/basic/anonymous/api/library/80869595-b7af-49e8-8ce6-870421a25b37/document/aae1fad2-38dd-4167-8a40-a1ac677f0cc3/media/testCheckLabelInCollection_file_cd6207d5-d57d-41b7-8b06-17b3d3c275b6" rel="enclosure" type="text/plain" title="testCheckLabelInCollection_file_cd6207d5-d57d-41b7-8b06-17b3d3c275b6" hreflang="en" length="68"></link>
      <link href="" rel="thumbnail"></link>
      <category term="document" scheme="tag:ibm.com,2006:td/type" label="document"></category>
      <link xmlns:thr="http://purl.org/syndication/thread/1.0" href="https://filesvm004.cn.ibm.com:9443/files/basic/api/library/80869595-b7af-49e8-8ce6-870421a25b37/document/aae1fad2-38dd-4167-8a40-a1ac677f0cc3/feed" rel="replies" type="application/atom+xml" thr:count="0"></link>
      <td:uuid xmlns:td="urn:ibm.com/td">aae1fad2-38dd-4167-8a40-a1ac677f0cc3</td:uuid>
      <td:added xmlns:td="urn:ibm.com/td">2015-07-28T05:01:31.834Z</td:added>
      <td:created xmlns:td="urn:ibm.com/td">2015-07-28T05:01:31.959Z</td:created>
      <published>2015-07-28T05:01:31.959Z</published>
      <updated>2015-07-28T05:01:32.255Z</updated>
      <td:modified xmlns:td="urn:ibm.com/td">2015-07-28T05:01:31.959Z</td:modified>
      <td:addedBy xmlns:td="urn:ibm.com/td">
         <name>Liz Schonfeld</name>
         <snx:userid xmlns:snx="http://www.ibm.com/xmlns/prod/sn">lschonfeld</snx:userid>
         <email>lschonfeld@renovations.com</email>
         <snx:userState xmlns:snx="http://www.ibm.com/xmlns/prod/sn">active</snx:userState>
      </td:addedBy>
      <author>
         <name>Liz Schonfeld</name>
         <snx:userid xmlns:snx="http://www.ibm.com/xmlns/prod/sn">lschonfeld</snx:userid>
         <email>lschonfeld@renovations.com</email>
         <snx:userState xmlns:snx="http://www.ibm.com/xmlns/prod/sn">active</snx:userState>
      </author>
      <td:modifier xmlns:td="urn:ibm.com/td">
         <name>Liz Schonfeld</name>
         <snx:userid xmlns:snx="http://www.ibm.com/xmlns/prod/sn">lschonfeld</snx:userid>
         <email>lschonfeld@renovations.com</email>
         <snx:userState xmlns:snx="http://www.ibm.com/xmlns/prod/sn">active</snx:userState>
      </td:modifier>
      <td:label xmlns:td="urn:ibm.com/td">testCheckLabelInCollection_file_cd6207d5-d57d-41b7-8b06-17b3d3c275b6</td:label>
      <td:libraryId xmlns:td="urn:ibm.com/td">80869595-b7af-49e8-8ce6-870421a25b37</td:libraryId>
      <td:libraryType xmlns:td="urn:ibm.com/td">personalFiles</td:libraryType>
      <td:versionUuid xmlns:td="urn:ibm.com/td">c2a318aa-a252-4056-80b3-a088ef9ec193</td:versionUuid>
      <td:versionLabel xmlns:td="urn:ibm.com/td">1</td:versionLabel>
      <summary type="text"></summary>
      <td:objectTypeName xmlns:td="urn:ibm.com/td">snx:file</td:objectTypeName>
      <td:propagation xmlns:td="urn:ibm.com/td">true</td:propagation>
      <snx:rank xmlns:snx="http://www.ibm.com/xmlns/prod/sn" scheme="http://www.ibm.com/xmlns/prod/sn/recommendations">0</snx:rank>
      <snx:rank xmlns:snx="http://www.ibm.com/xmlns/prod/sn" scheme="http://www.ibm.com/xmlns/prod/sn/comment">0</snx:rank>
      <snx:rank xmlns:snx="http://www.ibm.com/xmlns/prod/sn" scheme="http://www.ibm.com/xmlns/prod/sn/hit">0</snx:rank>
      <snx:rank xmlns:snx="http://www.ibm.com/xmlns/prod/sn" scheme="http://www.ibm.com/xmlns/prod/sn/anonymous_hit">0</snx:rank>
      <snx:rank xmlns:snx="http://www.ibm.com/xmlns/prod/sn" scheme="http://www.ibm.com/xmlns/prod/sn/share">0</snx:rank>
      <snx:rank xmlns:snx="http://www.ibm.com/xmlns/prod/sn" scheme="http://www.ibm.com/xmlns/prod/sn/collections">1</snx:rank>
      <snx:rank xmlns:snx="http://www.ibm.com/xmlns/prod/sn" scheme="http://www.ibm.com/xmlns/prod/sn/attachments">0</snx:rank>
      <snx:rank xmlns:snx="http://www.ibm.com/xmlns/prod/sn" scheme="http://www.ibm.com/xmlns/prod/sn/versions">1</snx:rank>
      <td:totalMediaSize xmlns:td="urn:ibm.com/td">68</td:totalMediaSize>
      <td:visibility xmlns:td="urn:ibm.com/td">public</td:visibility>
      <content type="application/atom+xml" src="https://filesvm004.cn.ibm.com:9443/files/basic/api/library/80869595-b7af-49e8-8ce6-870421a25b37/document/aae1fad2-38dd-4167-8a40-a1ac677f0cc3/media"></content>
      <td:restrictedVisibility xmlns:td="urn:ibm.com/td">false</td:restrictedVisibility>
      <td:lock xmlns:td="urn:ibm.com/td" type="NONE"></td:lock>
      <snx:isExternal xmlns:snx="http://www.ibm.com/xmlns/prod/sn">false</snx:isExternal>
   </entry>
</feed>