Skip to main content Skip to navigation

IT Services

Adding permissions

Adding permissions in the Atom Publishing Protocol is represented by sending a HTTP POST to a collection with an Atom document representing the file or folder's permissions. An example Atom representation of a new Files.Warwick permission might be as follows:

<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:files="http://go.warwick.ac.uk/elab-schemas/files/atom">
  <title>cuscav</title>
  <files:activity>VIEW</files:activity>
  <files:type>User</files:type>
  <content type="text" />
</entry>

Note that:

  • The <files:type> element specifies the type of permission
  • The <title> element contains who the permission is for. What you put here depends on the <files:type>element:
    • User - an individual usercode
    • Group - a Warwick web group
    • Anyone - (VIEW permissions only) anyone, whether logged in or not (the <title> is also set to Anyone)
    • Staff - (VIEW permissions only) any member of Staff (the <title> is also set to Staff)
    • Students - (VIEW permissions only) any Student (the <title> is also set to Students)
  • The files:activityelement contains the activity this permission represents. This is always one of:
    • VIEW (browse and download);
    • EDIT (upload, edit and delete); or
    • ADMIN (grant sharing rights)
  • The <title> element is the only required element; <files:type> defaults to User and <files:activity> defaults to VIEW

In order to add this permission, we need to POST it to the Collection of permissions for the folder or file. So if we want to add permissions to the root of your filespace, we need to POST it to the Collection page for Files/ (this is the root folder). We can see an example response (for the 'mmannion' account) in cURL (newpermission.atom is a file containing the content of the Atom document above; path is the location of the file or directory whose permissions are being altered, including the file name if applicable):

mat@augustus:~$ curl -i -X POST --data-binary @newpermission.atom -H 'Content-Type: application/atom+xml' -u cuscav
   "https://files.warwick.ac.uk/files/api/atom/permissions?account=mmannion&path=mmannion/Files/"
Enter host password for user 'cuscav':

HTTP/1.1 201 Created
Date: Thu, 11 Jul 2013 11:50:38 GMT
Location: https://files.warwick.ac.uk/files/api/atom/permission?account=mmannion&path=mmannion%2FFiles%2F&permission=ff8081813fcd8ee6013fcd9198f40002
Content-Type: application/atom+xml;charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:app="http://www.w3.org/2007/app"> xmlns:files="http://go.warwick.ac.uk/elab-schemas/files/atom" files:stereotype="permission"
  <title>cuscav</title>
  <link rel="collection" 
    href="https://files.warwick.ac.uk/files/api/atom/permissions?account=mmannion&path=mmannion%2FFiles%2F" />
  <link rel="edit" 
    href="https://files.warwick.ac.uk/files/api/atom/permission?account=mmannion&path=mmannion%2FFiles%2F&permission=ff8081813fcd8ee6013fcd9198f40002" />
  <link rel="alternate" 
    href="https://files.warwick.ac.uk/mmannion/browse/" />
  <id>urn:uuid:ff8081813fcd8ee6013fcd9198f40002</id>
  <author>
    <name>Mathew Mannion</name>
  </author>
  <summary type="text">VIEW for Mathew Mannion (cuscav)/</summary>
  <files:activity>VIEW</files:activity>
  <files:type>User</files:type>
</entry>

Note: it is important to send the Content-Type header. Failing to send this header will lead to a 500 Internal Server Error.

Some interesting things from the response:

  • Files.Warwick sends a 201 Created response, informing the client that a new permission has been created by the operation
  • The Location header contains the URL of the Atom representation of the newly created permission
  • The response is the Atom representation of the new permission (sending a GET request to the URL in the Location header will return the same content)
  • A link rel="collection" contains the location of the Atom Collection containing this permission; i.e. the collection that was just POSTed to

In the case of errors, we would get a HTTP 400 Bad Request response instead, with some explanatory text:

mat@augustus:~$ curl -i -X POST --data-binary @newpermission.atom -H 'Content-Type: application/atom+xml' -u cuscav
   "https://files.warwick.ac.uk/files/api/atom/permissions?account=mmannion&path=mmannion/Files/"
Enter host password for user 'cuscav':

HTTP/1.1 400 Bad Request
Date: Thu, 11 Jul 2013 11:54:16 GMT
Content-Type: text/plain;charset=utf-8

Couldn't create permission

org.springframework.validation.BeanPropertyBindingResult: 1 errors
Field error in object 'command' on field 'groupName': rejected value [cuscav]; codes [command.groupName,groupName,java.lang.String,]; arguments []; default message [Duplicate permissions]