Uploading a file in the Atom Publishing Protocol is represented by sending a HTTP POST to the file endpoint for a page. For example, to upload a file under /fac/sci/chemistry, we would send a HTTP POST to:

https://sitebuilder.warwick.ac.uk/sitebuilder2/edit/atom/file.htm?page=/fac/sci/chemistry

Rather than sending an XML representation of the file (as in Creating a new page) 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 link caption for the file, and also the URL of the file itself on the system. 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. It will be used as-is (minus extension) for the link caption, and used as the filename after converting any incompatible characters:

• my_document.doc: unchanged
• Picture of holiday.jpg: filename becomes picture_of_holiday.jpg, link title becomes "Picture of holiday"

So, as an example uploading the file output.pdf under /fac/sci/chemistry, with the link caption of "Exam Results" (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://sitebuilder.warwick.ac.uk/sitebuilder2/edit/atom/file.htm?page=/fac/sci/chemistry"
Enter host password for user 'cuscav':

HTTP/1.1 201 Created
Date: Tue, 22 Mar 2011 11:31:04 GMT
Server: Penny
Location: http://www2.warwick.ac.uk/fac/sci/chemistry/exam_results.pdf
Content-Length: 0
Vary: User-Agent
Content-Type: text/html

Some interesting things from the response:

• Sitebuilder sends a 201 Created response, informing the client that a new file has been created by the operation
• The Location header contains the URL of the newly uploaded file
• The response body is empty. An Atom representation of the file can still be obtained by accessing the single Atom representation of the file