pages/{pageid}/files/{filename}/description (PUT)
Overview
Update attachment description
- 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. |
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: