Skip to main content

Creating a new folder

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

<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <title>My new folder name</title>
  <content type="text" />
</entry>

Note that:

  • The <title> element contains the name of the new folder
  • The <title> element is the only required element; all other properties will be ignored (but it must be valid XML)

In order to create this folder, we need to POST it to the Collection of the parent folder. So if we want to create our new folder under 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 (newfolder.atom is a file containing the content of the Atom document above):

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

HTTP/1.1 201 Created
Date: Tue, 05 Mar 2013 15:02:24 GMT
Location: https://files.warwick.ac.uk/files/api/atom/node?account=mmannion&path=mmannion%2FFiles%2FMy+new+folder+name%2F
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"
  <title>My new folder name</title>
  <link rel="collection" 
    href="https://files.warwick.ac.uk/files/api/atom/folder?account=mmannion&path=mmannion%2FFiles%2FMy+new+folder+name%2F" />
  <link rel="edit" 
    href="https://files.warwick.ac.uk/files/api/atom/node?account=mmannion&path=mmannion%2FFiles%2FMy+new+folder+name%2F" />
  <link rel="alternate" 
    href="https://files.warwick.ac.uk/mmannion/browse/My+new+folder+name" />
  <id>https://files.warwick.ac.uk/mmannion/browse/My+new+folder+name</id>
  <updated>2013-03-05T15:02:24.658Z</updated>
  <published>2013-03-05T15:02:24.658Z</published>
  <app:edited>2013-03-05T15:02:24.658Z</app:edited>
  <author>
    <name>Mathew Mannion</name>
  </author>
  <summary type="text">My new folder name/</summary>
  <files:size>25053908</files:size>
  <files:files>10</files:files>
  <files:folders>2</files:folders>
</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 folder has been created by the operation
  • The Location header contains the URL of the Atom representation of the newly created folder
  • The response is the Atom representation of the new page (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 that this folder represents
  • If Files.Warwick has sanitised your folder name at all, this will be represented in the <title> element

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 @newfolder.atom -H 'Content-Type: application/atom+xml' -u cuscav
   "https://files.warwick.ac.uk/files/api/atom/folder?account=mmannion&path=mmannion/Files/"
Enter host password for user 'cuscav':

HTTP/1.1 400 Bad Request
Date: Tue, 05 Mar 2013 15:03:07 GMT
Content-Type: text/plain;charset=utf-8

Couldn't create folder

org.springframework.validation.BeanPropertyBindingResult: 1 errors
Field error in object 'command' on field 'folderName': rejected value [My new folder name]; codes [folderName.alreadyexists.command.folderName,folderName.alreadyexists.folderName,folderName.alreadyexists.java.lang.String,folderName.alreadyexists]; arguments []; default message [A folder with this name already exists.]