Developer:API permissions

Public Sharing permissions

As an interim measure, we allow the setting of public sharing options for resources uploaded via the API. At present, three basic sharing options are supported:

1. Resource is private
2. Resource can be viewed by the public
3. Resource can be viewed and downloaded by the public

The remainder of the sharing options are available as normal from the website after the upload. By default, resources will be uploaded with no public sharing at all. Only the uploader will be able to view, download or edit the resource.

If you supply a permissions element when creating or updating a resource, then (for the present time) please use exactly one of the following three fragments. More will follow when the general sharing API is complete.

Option 1: Resource is private

 <?xml version="1.0"?>
 <workflow>
   ...
   <permissions/>
 </workflow>

Option 2: Resource can be viewed by the public

 <?xml version="1.0"?>
 <workflow>
   ...
   <permissions>
     <permission>
       <category>public</category>
       <privilege type="view"/>
     </permission>
   </permissions>
 </workflow>

Option 3: Resource can be viewed and downloaded by the public

 <?xml version="1.0"?>
 <workflow>
   ...
   <permissions>
     <permission>
       <category>public</category>
       <privilege type="view"/>
       <privilege type="download"/>
     </permission>
   </permissions>
 </workflow>

Group Sharing Permissions

Resources can also be shared with groups in a similar manner. Creating a group permission will both "share" the resource with the specified group, and give all members of that group the specified access rights to the resource.

Group permissions share the same structure as public permissions, but have the category "group" and require an "id" element containing the groups myExperiment ID.

Multiple group permissions can be created.

Example 1: Private to anyone except group memebers

 <?xml version="1.0"?>
 <workflow>
   ...
   <permissions>
     <permission>
       <category>group</category>
       <id>123</id>
       <privilege type="view"/>
       <privilege type="download"/>
     </permission>
   </permissions>
 </workflow>

Example 2: Public can view and download, group memebers can edit

 <?xml version="1.0"?>
 <workflow>
   ...
   <permissions>
     <permission>
       <category>public</category>
       <privilege type="view"/>
       <privilege type="download"/>
     </permission>
     <permission>
       <category>group</category>
       <id>123</id>
       <privilege type="view"/>
       <privilege type="download"/>
       <privilege type="edit"/>
     </permission>
   </permissions>
 </workflow>

Example 3: Share with group, but don't give any special privileges for group members

 <?xml version="1.0"?>
 <workflow>
   ...
   <permissions>
     <permission>
       <category>public</category>
       <privilege type="view"/>
       <privilege type="download"/>
     </permission>
     <permission>
       <category>group</category>
       <id>123</id>
       <privilege type="view"/>
       <privilege type="download"/>
     </permission>
   </permissions>
 </workflow>

Example 4: Share with two groups, and also apply one group's skin

 <?xml version="1.0"?>
 <workflow>
   ...
   <permissions>
     <permission>
       <category>public</category>
       <privilege type="view"/>
       <privilege type="download"/>
     </permission>
     <permission>
       <category>group</category>
       <id>123</id>
       <privilege type="view"/>
       <privilege type="download"/>
     </permission>
     <permission>
       <category>group</category>
       <id>456</id>
       <privilege type="view"/>
       <privilege type="download"/>
       <use-layout>true</use-layout>
     </permission>
   </permissions>
 </workflow>

Implementation note

The current mapping from public privileges to share_mode/update_mode is as follows:

Public privileges	share_mode	update_mode
(none)	7	6
view	2	6
view and download	0	6

The current mapping from share_mode/update_mode to public privileges is as follows:

share_mode	update_mode	Public privileges
3,4,5,6,7,8	n/a	(none)
1,2	n/a	view
0	n/a	view and download