pages/{pageid}/files/{filename} (PUT)

Overview

Replace an existing attachment with a new version or create a new attachment

REST Method: PUT
Method Access: public

Uri Parameters

Name	Type	Description
filename	string	Double uri-encoded file name. Should be prefixed with "=" if it does not have an extension.
pageid	string	either an integer page ID, "home", or "=" followed by a double uri-encoded page path

Query Parameters

Name	Type	Description
redirects	int?	If zero, do not follow page redirects.
description	string?	file attachment description
authenticate	bool?	Force authentication for request (default: false)

Return Codes

Name	Value	Description
OK	200	The request completed successfully
Bad Request	400	Invalid input parameter or request body
Forbidden	403	Update access to the page is required
Not Found	404	Requested page could not be found

Message Format

Input:
File to upload

Output:

<file id="{int}" revision="{int}" href="{uri}">
    <filename>{text}</filename> 
    <description>{text}</description> 
    <contents type="{mimetype}" size="{int}" width="{int}" height="{int}" href="{uri}" /> 
    <contents.preview rel="thumb" type="{mimetype}" maxwidth="{int}" maxheight="{int}" href="{uri}" revision="{int}" /> 
    <contents.preview rel="webview" type="{mimetype}" maxwidth="{int}" maxheight="{int}" href="{uri}" revision="{int}" /> 
    <date.created>{date}</date.created> 
    <user.createdby id="{int}" href="{uri}">
        <nick>{text}</nick> 
        <username>{text}</username> 
        <email>{text}</email> 
    </user.createdby>
    <page.parent id="{int}" href="{uri}">
        <title>{text}</title> 
        <path>{text}</path> 
    </page.parent>
</file>

Implementation Notes

A single Expert site can store up to 5,000 attachments.

File uploads to template pages are not allowed.

If a file with the same name already exists on the specified page, a new revision of the existing file is uploaded. Otherwise, a new file is created.

The contents.preview element only exists if a file preview is available. Preview generation requires the file to be an image and fall within a certain size.

C# Sample: Upload a file to a page

The following code example uploads the file "myfile.jpg" to the home page:

Plug p = Plug.New("http://help.mindtouch.us/@api/deki");
p.At("users", "authenticate").WithCredentials("admin", "password").Get();
DreamMessage msg = DreamMessage.FromFile("c:\\temp\\myfile.jpg");
msg = p.At("pages", "home", "files", "=myfile%252ejpg").With("description", "File description text").Put(msg);

Sample response indicating that the second revision of "myfile.jpg" was successfully uploaded:

<file id="456" revision="2" href="http://help.mindtouch.us/@api/deki/files/456/info?revision=2">
    <filename>myfile.jpg</filename>
    <description>File description text</description>
    <contents type="image/jpeg" size="53112" width="476" height="480" href="http://help.mindtouch.us/@api/deki/files/456?revision=2" />
    <contents.preview rel="thumb" type="image/jpeg" maxwidth="160" maxheight="160" href="http://help.mindtouch.us/@api/deki/files/456?revision=2&amp;size=thumb" revision="2" />
    <contents.preview rel="webview" type="image/jpeg" maxwidth="550" maxheight="550" href="http://help.mindtouch.us/@api/deki/files/456?revision=2&amp;size=webview" revision="2" />
    <date.created>2007-09-06T19:23:21Z</date.created>
    <user.createdby id="1" href="http://help.mindtouch.us/@api/deki/users/1">
        <nick>Admin</nick>
        <username>Admin</username>
        <email>admin@mindtouch.com</email>
    </user.createdby>
    <page.parent id="29" href="http://help.mindtouch.us/@api/deki/pages/29">
        <title>DekiWiki (Hayes)</title>
        <path></path>
    </page.parent>
</file>

Implementation notes

Add notes about requirements or config values

Curl Sample: Upload an image to a page

The following curl command issues a PUT request to send file "foo.jpg" and upload it to page "test" under the name "bar.jpg".

Sample Code

curl -u username:password -T foo.jpg -i http://mindtouch.address/@api/deki/pages/=test/files/=bar.jpg

Implementation notes

curl flags

-u: Basic HTTP authentication. Sends a username and password to server so it can verify whether a user is of privilege to perform specific operation.
-T: Sends a file using the PUT command.

-i: Includes the HTTP response header in the output. Useful for debugging.

Example

The following curl command will attach the (legal) image "patrickstewart.jpg" to Jean Luc Picard's page under the name "captain.jpg".

patrickstewart.jpg

Sample Code

curl -u username:password -T patrickstewart.jpg -i http://192.168.168.110/@api/deki/pages/=Jean%2520Luc%2520Picard/files/=captain.jpg

HTTP Response Headers

HTTP/1.1 200 OK
Date: Fri, 08 Jan 2010 23:38:21 GMT
Server: Dream-HTTPAPI/1.7.2.17433
X-Deki-Site: id="default"
Content-Type: application/xml; charset=utf-8
Content-Length: 1285
Via: 1.1 dekiwiki

HTTP Response Body

Content-Type: application/xml

<?xml version="1.0"?>
<file id="9" href="http://192.168.168.110/@api/deki/files/9/info">
  <filename>captain.jpg</filename>
  <description/>
  <contents type="application/octet-stream" size="495835" width="1691" height="2343" href="http://192.168.168.110/@api/deki/files/9/=captain.jpg"/>
  <contents.preview rel="thumb" type="image/jpeg" maxwidth="160" maxheight="160" href="http://192.168.168.110/@api/deki/files/9/=captain.jpg?size=thumb"/>
  <contents.preview rel="webview" type="image/jpeg" maxwidth="550" maxheight="550" href="http://192.168.168.110/@api/deki/files/9/=captain.jpg?size=webview"/>
  <date.created>2010-01-08T23:37:56Z</date.created>
  <user.createdby id="1" href="http://192.168.168.110/@api/deki/users/1">
    <nick>Admin</nick>
    <username>Admin</username>
    <email>melder@mindtouch.com</email>
    <hash.email>637b79dca5c8ebdc4347bccca42d3487</hash.email>
    <uri.gravatar>http://www.gravatar.com/avatar/637b79dca5c8ebdc4347bccca42d3487</uri.gravatar>
  </user.createdby>
  <revisions count="2" totalcount="2" href="http://192.168.168.110/@api/deki/files/9/revisions"/>
  <page.parent id="51" href="http://192.168.168.110/@api/deki/pages/51?redirects=0">
    <uri.ui>http://192.168.168.110/Jean_Luc_Picard</uri.ui>
    <title>Jean Luc Picard</title>
    <path>Jean_Luc_Picard</path>
    <namespace>main</namespace>
  </page.parent>
</file>

Notes

The page path is double encoded. In the above example, spaces in "Jean Luc Picard" are replaced with %2520.
Running the command again with the same path will overwrite the stored image.