Uploading a file

Uploading a file in the Atom Publishing Protocol is represented by sending a HTTP POST to the Atom collection for the parent folder. For example, to upload a file under the root of the 'mmannion' account, we would send a HTTP POST to:

https://files.warwick.ac.uk/files/api/atom/folder?account=mmannion&path=mmannion/Files/

This is exactly the same endpoint that we send a POST to when creating a new folder. Rather than sending an XML representation of the file, we send the file contents itself as the body of the POST request. Because we can't set initial properties in the Atom representation, we use the "Slug" HTTP Header to set the filename of the file, and this corresponds to the URL of the file itself in Files.Warwick. We also need to set the Content-Type header correctly to the MIME type of the uploaded file.

The slug header should either be the filename, or a more descriptive name.

So, as an example uploading the file output.pdf under mmannion/Files/, with the filename of "Exam Results.pdf" (note cURL may send a number of 100 Continue intermediate responses as the file is uploaded):

mat@augustus:~$ curl -i -X POST --data-binary @output.pdf -H 'Content-Type: application/pdf' -H 'Slug: Exam Results.pdf' -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 16:38:35 GMT
Location: https://files.warwick.ac.uk/files/api/atom/node?account=mmannion&path=mmannion%2FFiles%2FExam+Results.pdf
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>Exam Results.pdf</title>
  <link rel="edit" href="https://files.warwick.ac.uk/files/api/atom/node?account=mmannion&path=mmannion%2FFiles%2FExam+Results.pdf"/>
  <link rel="edit-media" href="https://files.warwick.ac.uk/files/api/atom/media?account=mmannion&path=mmannion%2FFiles%2FExam+Results.pdf"/>
  <link rel="alternate" type="application/pdf" href="https://files.warwick.ac.uk/mmannion/files/Exam+Results.pdf"/>
  <content type="application/pdf" src="https://files.warwick.ac.uk/mmannion/files/Exam+Results.pdf"/>
  <id>https://files.warwick.ac.uk/mmannion/files/Exam+Results.pdf</id>
  <updated>2013-03-05T16:38:34.971Z</updated>
  <published>2013-03-05T16:38:35.023Z</published>
  <app:edited>2013-03-05T16:38:34.971Z</app:edited>
  <author>
    <name>Mathew Mannion</name>
  </author>
  <summary type="text">Exam Results.pdf</summary>
  <files:mimetype>application/pdf</files:mimetype>
  <files:size>11923854</files:size>
  <files:antivirus>
    <files:checking>false</files:checking>
    <files:checked>true</files:checked>
    <files:hasvirus>false</files:hasvirus>
  </files:antivirus>
</entry>

Some interesting things from the response:

Files.Warwick sends a 201 Created response, informing the client that a new file has been created by the operation
The Location header contains the URL to the Atom representation of the newly uploaded file
The response contains the Atom representation of the newly uploaded file - a GET to the URL in the Location header will return identical content