Community articleRetrieving the list of roles for a folderSince V5.5
Added by IBM contributorIBM on August 20, 2015
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

Retrieve the list of access roles assigned to a folder.
Authentication is not required for public folders, but is required for folders that are owned by users.

If authentication is required, the user must have 'View' permission on the folder. View permission is granted through the Reader, Contributor, or Manager role of a folder. To test whether the current user can get a list of roles of a folder, use the API for Retrieving the list of members for a folder's role to see if the user belongs to one of the required roles.


The following access roles are available:

Role Type
Permissions
Reader
View a folder and all media in it.
Contributor
Add to a folder and delete items they added.
Manager
Add and remove any item; assign roles.

The following error codes could appear in a response body for an invalid request:

Error Code
Description
Unknown
Returned when the cause of an error is unknown
ItemNotFound
Returned when the cause of an error is related to a resource not being found
Input
Method URI Description
GET /files/{auth}/api/collection/{collection-id}/roles Retrieve the complete list of access roles for the specified folder.
GET /files/{auth}/api/communitycollection/{community-id}/roles Retrieve the complete list of access roles for the specified community folder.
Name Type Optional Description
auth
enumerated No The authorization protocol being used by your application to access Connections Cloud.
Authorized values:
  • basic
  • oauth
collection-id
string No The UUID of the folder for which you want to retrieve roles.
community-id
string No The UUID of the community folder for which you want to retrieve roles.
Name Type Optional Description
rep
enumerated Yes Defines the level of detail in the returned entry elements. The default value is full.
Authorized values:
  • compact
  • full
resolve-membership
enumerated Yes Determines whether membership details are merged in the feed. This parameter is only valid if rep attribute is set to full. The default value for this parameter is false.
Authorized values:
  • true
  • false
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:
  • basic
  • bearer
Output
Code Description
401
Unauthorized. Returned when no authenticated user or no userid, email, or key parameter are provided on the request.
Examples
Retrieve the list of access roles and include details. The rep parameter is omitted so its value defaults to full, which means that the resolve-membership parameter will be processed.
GET /files/basic/api/collection/13586417-0f56-4aaf-a2f7-5726d1093e4c/roles?resolve-membership=true

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">
   <title type="text">Roles of testPostGetCollectionRolesFeed_contributor_public_1436165993291</title>
   <author>
      <name>Administrator</name>
   </author>
   <link href="https://filesvm004.cn.ibm.com:9443/files/basic/api/collection/13586417-0f56-4aaf-a2f7-5726d1093e4c/roles" rel="self"></link>
   <id>ca:/collection/13586417-0f56-4aaf-a2f7-5726d1093e4c/roles</id>
   <updated>2015-07-06T07:00:24.928Z</updated>
   <generator version="0.0.0.0" uri="http://www.ibm.com/xmlns/prod/sn">IBM Connections - Files</generator>
   <entry>
      <title type="text">manager</title>
      <author>
         <name>Administrator</name>
      </author>
      <id>ca:/collection/13586417-0f56-4aaf-a2f7-5726d1093e4c/roles/manager</id>
      <link href="https://filesvm004.cn.ibm.com:9443/files/basic/api/collection/13586417-0f56-4aaf-a2f7-5726d1093e4c/roles/manager" rel="self" type="application/atom+xml"></link>
      <link xmlns:ca="http://www.ibm.com/xmlns/prod/composite-applications/v1.0" href="https://filesvm004.cn.ibm.com:9443/files/basic/api/collection/13586417-0f56-4aaf-a2f7-5726d1093e4c/roles/manager/members" rel="related" type="application/atom+xml" ca:rel="members"></link>
      <updated>2015-07-06T07:00:24.928Z</updated>
      <content type="application/xml">
         <ca:role xmlns:ca="http://www.ibm.com/xmlns/prod/composite-applications/v1.0" ca:id="manager%4013586417-0f56-4aaf-a2f7-5726d1093e4c" ca:type="manager">
            <ca:title xmlns:td="urn:ibm.com/td" xmlns:ca="http://www.ibm.com/xmlns/prod/composite-applications/v1.0" td:language="en">manager</ca:title>
            <td:nonVisibleGroupCount xmlns:td="urn:ibm.com/td">0</td:nonVisibleGroupCount>
            <ca:member xmlns:snx="http://www.ibm.com/xmlns/prod/sn" xmlns:ca="http://www.ibm.com/xmlns/prod/composite-applications/v1.0" ca:id="lschonfeld" ca:type="user" ca:email="lschonfeld@renovations.com" snx:userState="active" ca:display-name="Liz Schonfeld"></ca:member>
         </ca:role>
      </content>
   </entry>
   <entry>
      <title type="text">reader</title>
      <author>
         <name>Administrator</name>
      </author>
      <id>ca:/collection/13586417-0f56-4aaf-a2f7-5726d1093e4c/roles/reader</id>
      <link href="https://filesvm004.cn.ibm.com:9443/files/basic/api/collection/13586417-0f56-4aaf-a2f7-5726d1093e4c/roles/reader" rel="self" type="application/atom+xml"></link>
      <link xmlns:ca="http://www.ibm.com/xmlns/prod/composite-applications/v1.0" href="https://filesvm004.cn.ibm.com:9443/files/basic/api/collection/13586417-0f56-4aaf-a2f7-5726d1093e4c/roles/reader/members" rel="related" type="application/atom+xml" ca:rel="members"></link>
      <updated>2015-07-06T07:00:24.928Z</updated>
      <content type="application/xml">
         <ca:role xmlns:ca="http://www.ibm.com/xmlns/prod/composite-applications/v1.0" ca:id="reader%4013586417-0f56-4aaf-a2f7-5726d1093e4c" ca:type="reader">
            <ca:title xmlns:td="urn:ibm.com/td" xmlns:ca="http://www.ibm.com/xmlns/prod/composite-applications/v1.0" td:language="en">reader</ca:title>
            <td:nonVisibleGroupCount xmlns:td="urn:ibm.com/td">0</td:nonVisibleGroupCount>
            <ca:member xmlns:ca="http://www.ibm.com/xmlns/prod/composite-applications/v1.0" ca:type="virtual" ca:id="all-authenticated-users" ca:display-name="All Authenticated Users"></ca:member>
            <ca:member xmlns:ca="http://www.ibm.com/xmlns/prod/composite-applications/v1.0" ca:type="virtual" ca:id="anonymous-user" ca:display-name="Anonymous User"></ca:member>
         </ca:role>
      </content>
   </entry>
   <entry>
      <title type="text">editor</title>
      <author>
         <name>Administrator</name>
      </author>
      <id>ca:/collection/13586417-0f56-4aaf-a2f7-5726d1093e4c/roles/editor</id>
      <link href="https://filesvm004.cn.ibm.com:9443/files/basic/api/collection/13586417-0f56-4aaf-a2f7-5726d1093e4c/roles/editor" rel="self" type="application/atom+xml"></link>
      <link xmlns:ca="http://www.ibm.com/xmlns/prod/composite-applications/v1.0" href="https://filesvm004.cn.ibm.com:9443/files/basic/api/collection/13586417-0f56-4aaf-a2f7-5726d1093e4c/roles/editor/members" rel="related" type="application/atom+xml" ca:rel="members"></link>
      <updated>2015-07-06T07:00:24.928Z</updated>
      <content type="application/xml">
         <ca:role xmlns:ca="http://www.ibm.com/xmlns/prod/composite-applications/v1.0" ca:id="editor%4013586417-0f56-4aaf-a2f7-5726d1093e4c" ca:type="editor">
            <ca:title xmlns:td="urn:ibm.com/td" xmlns:ca="http://www.ibm.com/xmlns/prod/composite-applications/v1.0" td:language="en">editor</ca:title>
            <td:nonVisibleGroupCount xmlns:td="urn:ibm.com/td">0</td:nonVisibleGroupCount>
            <ca:member xmlns:snx="http://www.ibm.com/xmlns/prod/sn" xmlns:ca="http://www.ibm.com/xmlns/prod/composite-applications/v1.0" ca:id="aberzat" ca:type="user" ca:email="aberzat@renovations.com" snx:userState="active" ca:display-name="Andreas Berzat"></ca:member>
            <ca:member xmlns:ca="http://www.ibm.com/xmlns/prod/composite-applications/v1.0" ca:id="group_share_dev" ca:type="group" ca:display-name="group_share_dev"></ca:member>
         </ca:role>
      </content>
   </entry>
   <entry>
      <td:deprecated xmlns:td="urn:ibm.com/td">
         <td:advice xmlns:td="urn:ibm.com/td">ca:/collection/13586417-0f56-4aaf-a2f7-5726d1093e4c/roles/editor</td:advice>
      </td:deprecated>
      <title type="text">contributor</title>
      <author>
         <name>Administrator</name>
      </author>
      <id>ca:/collection/13586417-0f56-4aaf-a2f7-5726d1093e4c/roles/contributor</id>
      <link href="https://filesvm004.cn.ibm.com:9443/files/basic/api/collection/13586417-0f56-4aaf-a2f7-5726d1093e4c/roles/contributor" rel="self" type="application/atom+xml"></link>
      <link xmlns:ca="http://www.ibm.com/xmlns/prod/composite-applications/v1.0" href="https://filesvm004.cn.ibm.com:9443/files/basic/api/collection/13586417-0f56-4aaf-a2f7-5726d1093e4c/roles/contributor/members" rel="related" type="application/atom+xml" ca:rel="members"></link>
      <updated>2015-07-06T07:00:24.928Z</updated>
      <content type="application/xml">
         <ca:role xmlns:ca="http://www.ibm.com/xmlns/prod/composite-applications/v1.0" ca:id="contributor%4013586417-0f56-4aaf-a2f7-5726d1093e4c" ca:type="contributor">
            <ca:title xmlns:td="urn:ibm.com/td" xmlns:ca="http://www.ibm.com/xmlns/prod/composite-applications/v1.0" td:language="en">contributor</ca:title>
            <td:nonVisibleGroupCount xmlns:td="urn:ibm.com/td">0</td:nonVisibleGroupCount>
            <ca:member xmlns:snx="http://www.ibm.com/xmlns/prod/sn" xmlns:ca="http://www.ibm.com/xmlns/prod/composite-applications/v1.0" ca:id="aberzat" ca:type="user" ca:email="aberzat@renovations.com" snx:userState="active" ca:display-name="Andreas Berzat"></ca:member>
            <ca:member xmlns:ca="http://www.ibm.com/xmlns/prod/composite-applications/v1.0" ca:id="group_share_dev" ca:type="group" ca:display-name="group_share_dev"></ca:member>
         </ca:role>
      </content>
   </entry>
</feed>