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

Overview

Update attachment description

Uri Parameters

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

Query Parameters

Name Type Description
authenticate bool? Force authentication for request (default: false)
redirects int? If zero, do not follow page redirects (only applies when {pageid} is present).

Return Codes

Name Value Description
OK 200 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 file could not be found

Message Format

Input:
Content-type=text/plain

Output:

<file id="{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}" /> 
    <contents.preview rel="webview" type="{mimetype}" maxwidth="{int}" maxheight="{int}" href="{uri}" /> 
    <date.created>{date}</date.created> 
    <user.createdby id="{int}" href="{uri}">
        <nick>{text}</nick> 
        <username>{text}</username> 
        <email>{text}</email> 
    </user.createdby>
    <revisions count="{int}" href="{uri}" /> 
    <page.parent id="{int}" href="{uri}">
        <title>{text}</title> 
        <path>{text}</path> 
    </page.parent>
</file>

Implementation Notes

Use GET:files/{fileid}/description to retrieve the file description.

C# Sample: Set File Description

The following code example sets the description of the file "myfile.jpg" on the home page:

Sample Code

Plug p = Plug.New("http://help.mindtouch.us/@api/deki");
p.At("users", "authenticate").WithCredentials("admin", "password").Get();
DreamMessage msg = DreamMessage.Ok(MimeType.TEXT, "New description text");
p.At("pages", "home", "files", "=myfile%252ejpg", "description").Put(msg);

Sample Response from executing Code

<file id="456" href="http://help.mindtouch.us/@api/deki/files/456/info">
    <filename>myfile.jpg</filename> 
    <description>New description text</description> 
    <contents type="image/pjpeg" size="53112" width="476" height="480" href="http://help.mindtouch.us/@api/deki/files/456" /> 
    <contents.preview rel="thumb" type="image/pjpeg" maxwidth="160" maxheight="160" href="http://help.mindtouch.us/@api/deki/files/456?size=thumb" /> 
    <contents.preview rel="webview" type="image/pjpeg" maxwidth="550" maxheight="550" href="http://help.mindtouch.us/@api/deki/files/456?size=webview" /> 
    <date.created>2007-08-27T19:59:24Z</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>
    <revisions count="2" href="http://help.mindtouch.us/@api/deki/files/456/revisions" /> 
    <page.parent id="29" href="http://help.mindtouch.us/@api/deki/pages/29">
        <title>DekiWiki (Hayes)</title> 
        <path /> 
    </page.parent>
</file>

Implementation notes

Curl Sample: Set File Description

The following curl command will set or replace a description of file "foo" on page "bar". The description itself is read out of file "description.txt".

Sample Code

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

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

An image, trollface.jpg, is sitting without description in page Meme. The file problem.txt contains the description we want to set.

problem.txt

Content-Type: text/plain

Problem?

Sample Code

curl -u username:password -T problem.txt -i http://192.168.168.110/@api/deki/pages/=meme/files/=trollface.jpg/description

HTTP Response Headers

HTTP/1.1 200 OK
Date: Sat, 09 Jan 2010 01:58:39 GMT
Server: Dream-HTTPAPI/1.7.2.17433
X-Deki-Site: id="default"
Content-Type: application/xml; charset=utf-8
Content-Length: 2098
Via: 1.1 dekiwiki

HTTP Response Body

Content-Type: application/xml

<?xml version="1.0"?>
<file id="10" href="http://192.168.168.110/@api/deki/files/10/info">
  <filename>trollface.jpg</filename>
  <description>Problem?</description>
  <contents type="image/jpeg" size="88820" width="469" height="428" href="http://192.168.168.110/@api/deki/files/10/=trollface.jpg"/>
  <contents.preview rel="thumb" type="image/jpeg" maxwidth="160" maxheight="160" href="http://192.168.168.110/@api/deki/files/10/=trollface.jpg?size=thumb"/>
  <contents.preview rel="webview" type="image/jpeg" maxwidth="550" maxheight="550" href="http://192.168.168.110/@api/deki/files/10/=trollface.jpg?size=webview"/>
  <date.created>2010-01-09T01:53:38Z</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="1" totalcount="1" href="http://192.168.168.110/@api/deki/files/10/revisions"/>
  <page.parent id="68" href="http://192.168.168.110/@api/deki/pages/68?redirects=0">
    <uri.ui>http://192.168.168.110/Meme</uri.ui>
    <title>Meme</title>
    <path>Meme</path>
    <namespace>main</namespace>
  </page.parent>
  <properties count="1" href="http://192.168.168.110/@api/deki/files/10/properties">
    <property name="urn:deki.mindtouch.com#description" href="http://192.168.168.110/@api/deki/files/10/properties/urn%253adeki.mindtouch.com%2523description/info" etag="28.r1_ts2010-01-09T01:58:39Z">
      <contents type="text/plain; charset=utf-8" size="8" href="http://192.168.168.110/@api/deki/files/10/properties/urn%253adeki.mindtouch.com%2523description">Problem?</contents>
      <date.modified>2010-01-09T01:58:39Z</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>Deki/API Reference/PUT:pages/{pageid}/files/{filename}/description/Curl Code Samples/Page Title - Edit - MindTouch Community Portal        <uri.gravatar>http://www.gravatar.com/avatar/637b79dca5c8ebdc4347bccca42d3487</uri.gravatar>
      </user.modified>
    </property>
  </properties>
</file>

Notes

  • Running the command on an existing description will overwrite it.
  • The result:

 

 description.png