files/{fileid} (PUT)

Overview

Replace an existing attachment with a new version

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 title

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

Output:

<file id="{id}" revision="{int}" href="{uri}">
  <filename>{text}</filename>
  <description>{text}</description>
  <contents type="{MIME}" size="{int}" href="{uri}"/>
  <date.created>{date}</date.created>
  <user.createdby id="{int}" href="{uri}">
    <nick>{text}</nick>
    <username>{text}</username>
    <fullname>{text}</fullname>
    <email>{text}</email>
    <hash.email>{hash}</hash.email>
    <uri.gravatar>{uri}</uri.gravatar>
  </user.createdby>
  <revisions count="{int}" totalcount="{int}" href="{uri}"/>
  <page.parent id="{int}" href="{uri}">
    <uri.ui>{uri}</uri.ui>
    <title>{text}</title>
    <path>{text}</path>
    <namespace>{namespace}</namespace>
  </page.parent>
  <properties/>
</file>

Implementation Notes

Replaces an existing file.

Curl Sample: Replace a File

The following command can be used to replace an existing file. In this case, a file with file ID = 1 is replaced by image foo.jpg. Note that the file does not have to be an image. Also, a file with file ID = 1 must exist for the operation to succeed.

Sample Code

curl -u username:password -H "Content-Type: image/jpg" -T foo.jpg -i http://192.168.168.110/@api/deki/files/1

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.

MIMEs

It's important to specify a MIME type in the "Content-Type" header for the server to process the file correctly.

Example

A user uploaded a copyright image (File ID = 9). The use of such image has brought on the heat of the digital police. Instead of removing it, we will replace it with the copyright sign.

copyright.png

Sample Code

curl -u username:password -H "Content-Type: image/png" -T copyright.png -i http://192.168.168.110/@api/deki/files/9

HTTP Response Headers

HTTP/1.1 200 OK
Date: Tue, 12 Jan 2010 19:11:40 GMT
Server: Dream-HTTPAPI/1.7.2.17433
X-Deki-Site: id="default"
Content-Type: application/xml; charset=utf-8
Content-Length: 2790
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>image 9</description>
  <contents type="image/png" size="12557" width="1691" height="2343" href="http://192.168.168.110/@api/deki/files/9/=captain.jpg"/>
  <contents.preview rel="thumb" type="image/png" maxwidth="160" maxheight="160" href="http://192.168.168.110/@api/deki/files/9/=captain.jpg?size=thumb"/>
  <contents.preview rel="webview" type="image/png" maxwidth="550" maxheight="550" href="http://192.168.168.110/@api/deki/files/9/=captain.jpg?size=webview"/>
  <date.created>2010-01-12T19:11:39Z</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="5" totalcount="5" 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>
  <properties count="2" href="http://192.168.168.110/@api/deki/files/9/properties">
    <property name="urn:deki.mindtouch.com#description" href="http://192.168.168.110/@api/deki/files/9/properties/urn%253adeki.mindtouch.com%2523description/info" etag="29.r2_ts2010-01-11T20:42:40Z">
      <contents type="text/plain; charset=utf-8" size="7" href="http://192.168.168.110/@api/deki/files/9/properties/urn%253adeki.mindtouch.com%2523description">image 9</contents>
      <date.modified>2010-01-11T20:42:40Z</date.modified>
      <user.modified 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.modified>
    </property>
    <property name="iscopyright" href="http://192.168.168.110/@api/deki/files/9/properties/iscopyright/info" etag="34.r1_ts2010-01-12T00:41:49Z">
      <contents type="text/plain" size="2" href="http://192.168.168.110/@api/deki/files/9/properties/iscopyright">no</contents>
      <date.modified>2010-01-12T00:41:49Z</date.modified>
      <user.modified 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.modified>
      <change-description/>
    </property>
  </properties>
</file>