files/{fileid}/{filename} (PUT)

Overview

Replace an existing attachment with a new version

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

This feature works in exactly same way PUT:/files/{fileid} does. A doubly encoded filename can be appended to the end of the path to designate the desired filename on the Expert filesystem.

Curl Sample: Update a File

The following command updates a file (file ID = 1) with the file "foo". The stored file name will be "bar".

Sample Code

curl -u username:password -H "Content-Type: xxx" -T foo -i http://192.168.59.128/@api/deki/files/1/=bar

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.
-H
Adds a header or modifies an existing one. This is used to modify the "Content-Type" HTTP request header. Remember to set it to the appropriate MIME according to the file uploaded (for example image/jpg for a jpeg image).
-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

We at Expert love playing pranks on each other. So we are going to update an existing image to one that which will most likely annoy a user. The following demonstrates how to change a file (file ID = 71) to an image, "troll.jpg". The image will be named "trollface.jpg" in the Mindtouch directory.

Sample Code

curl -u admin:password -H "Content-Type: image/jpg" -T trollface.jpg -i http://192.168.59.128/@api/deki/files/71/=trollface.jpg

HTTP Response Headers

HTTP/1.1 200 OK
Date: Thu, 21 Jan 2010 22:49:11 GMT
Server: Dream-HTTPAPI/2.0.0.17629 Microsoft-HTTPAPI/2.0
Content-Length: 2022
Content-Type: application/xml; charset=utf-8
X-Data-Stats: request-time-ms=1919; mysql-queries=21; mysql-time-ms=143;
X-Deki-Site: id="default"
Via: 1.1 dekiwiki

HTTP Response Body

Content-Type: application/xml

<?xml version="1.0"?>
<file id="71" revision="5" href="http://192.168.59.128/@api/deki/files/71/info">
  <filename>trollface.jpg</filename>
  <description/>
  <contents type="image/jpg" size="88820" width="469" height="428" href="http://192.168.59.128/@api/deki/files/71/=trollface.jpg"/>
  <contents.preview rel="thumb" type="image/jpeg" maxwidth="160" maxheight="160" href="http://192.168.59.128/@api/deki/files/71/=trollface.jpg?size=thumb"/>
  <contents.preview rel="webview" type="image/jpeg" maxwidth="550" maxheight="550" href="http://192.168.59.128/@api/deki/files/71/=trollface.jpg?size=webview"/>
  <date.created>2010-01-21T22:49:09Z</date.created>
  <user.createdby id="1" href="http://192.168.59.128/@api/deki/users/1">
    <nick>Admin</nick>
    <username>Admin</username>
    <email>admin@admin.com</email>
    <hash.email>64e1b8d34f425d19e1ee2ea7236d3028</hash.email>
    <uri.gravatar>http://www.gravatar.com/avatar/64e1b8d34f425d19e1ee2ea7236d3028</uri.gravatar>
  </user.createdby>
  <revisions count="5" totalcount="5" href="http://192.168.59.128/@api/deki/files/71/revisions"/>
  <page.parent id="567" href="http://192.168.59.128/@api/deki/pages/567?redirects=0">
    <uri.ui>http://192.168.59.128/FUBAR</uri.ui>
    <title>FUBAR</title>
    <path>FUBAR</path>
    <namespace>main</namespace>
  </page.parent>
  <properties count="1" href="http://192.168.59.128/@api/ deki/files/71/properties">
    <property name="iscopyright" href="http://192.168.59.128/@api/deki/files/71/properties/iscopyright/info" etag="106.r2_ts2010-01-21T19:54:52Z">
      <contents type="text/plain" size="3" href="http://192.168.59.128/@api/deki/files/71/properties/iscopyright">yes</contents>
      <date.modified>2010-01-21T19:54:52Z</date.modified>
      <user.modified id="1" href="http://192.168.59.128/@api/deki/users/1">
        <nick>Admin</nick>
        <username>Admin</username>
        <email>admin@admin.com</email>
        <hash.email>64e1b8d34f425d19e1ee2ea7236d3028</hash.email>
        <uri.gravatar>http://www.gravatar.com/avatar/64e1b8d34f425d19e1ee2ea7236d3028</uri.gravatar>
      </user.modified>
      <change-description/>
    </property>
  </properties>
</file>