files/{fileid}/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 title |
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:
01 | < file id = "{int}" href = "{uri}" > |
02 | < filename >{text}</ filename > |
03 | < description >{text}</ description > |
04 | < contents type = "{mimetyp e}" size = "{int}" width = "{int}" height = "{int}" href = "{uri}" /> |
05 | < contents.preview rel = "thumb" type = "{mimetype}" maxwidth = "{int}" maxheight = "{int}" href = "{uri}" /> |
06 | < contents.preview rel = "webview" type = "{mimetype}" maxwidth = "{int}" maxheight = "{int}" href = "{uri}" /> |
07 | < date.created >{date}</ date.created > |
08 | < user.createdby id = "{int}" href = "{uri}" > |
09 | < nick >{text}</ nick > |
10 | < username >{text}</ username > |
11 | < email >{text}</ email > |
12 | </ user.createdby > |
13 | < revisions count = "{int}" href = "{uri}" /> |
14 | < page.parent id = "{int}" href = "{uri}" > |
15 | < title >{text}</ title > |
16 | < path >{text}</ path > |
17 | </ page.parent > |
18 | </ 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 with ID 456:
Sample Code
1 | Plug p = Plug.New( "http://help.mindtouch.us/@api/deki" ); |
2 | p.At( "users" , "authenticate" ).WithCredentials( "admin" , "password" ).Get(); |
3 | DreamMessage msg = DreamMessage.Ok(MimeType.TEXT, "File description text" ); |
4 | p.At( "files" , "456" , "description" ).Put(msg); |
Sample Response from executing Code
01 | < file id = "456" href = "http://help.mindtouch.us/@api/deki/files/456/info" > |
02 | < filename >myfile.jpg</ filename > |
03 | < description >File description text</ description > |
04 | < contents type = "image/pjpeg" size = "53112" width = "476" height = "480" href = "http://help.mindtouch.us/@api/deki/files/456" /> |
05 | < contents.preview rel = "thumb" type = "image/pjpeg" maxwidth = "160" maxheight = "160" href = "http://help.mindtouch.us/@api/deki/files/456?size=thumb" /> |
06 | < contents.preview rel = "webview" type = "image/pjpeg" maxwidth = "550" maxheight = "550" href = "http://help.mindtouch.us/@api/deki/files/456?size=webview" /> |
07 | < date.created >2007-08-27T19:59:24Z</ date.created > |
08 | < user.createdby id = "1" href = "http://help.mindtouch.us/@api/deki/users/1" > |
09 | < nick >Admin</ nick > |
10 | < username >Admin</ username > |
11 | < email >admin@mindtouch.com</ email > |
12 | </ user.createdby > |
13 | < revisions count = "2" href = "http://help.mindtouch.us/@api/deki/files/456/revisions" /> |
14 | < page.parent id = "29" href = "http://help.mindtouch.us/@api/deki/pages/29" > |
15 | < title >DekiWiki (Hayes)</ title > |
16 | < path /> |
17 | </ page.parent > |
18 | </ file > |
Curl Sample: Set File Description
The following curl command will set or replace a description of a file according to its fileid (42, in the example). The description string is read out of file "description.txt".
Sample Code
1 | curl -u username:password -T description.txt -i http://192.168.168.110/@api/deki/files/42/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 with image id 9 exists. We want to change its description to something generic, like "image 9". The file generic.txt contains the description we want to set.
generic.txt
Content-Type: text/plain
image 9
Sample Code
1 | curl -u username:password -T generic.txt -i http://192.168.168.110/@api/deki/files/9/description |
HTTP Response Headers
HTTP/1.1 200 OK Date: Mon, 11 Jan 2010 20:26:05 GMT Server: Dream-HTTPAPI/1.7.2.17433 X-Deki-Site: id="default" Content-Type: application/xml; charset=utf-8 Content-Length: 2129 Via: 1.1 dekiwiki
HTTP Response Body
Content-Type: application/xml
01 | <? xml version = "1.0" ?> |
02 | < file id = "9" href = "http://192.168.168.110/@api/deki/files/9/info" > |
03 | < filename >captain.jpg</ filename > |
04 | < description >image 9</ description > |
05 | < contents type = "application/octet-stream" size = "495835" width = "1691" height = "2343" href = "http://192.168.168.110/@api/deki/files/9/=captain.jpg" /> |
06 | < 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" /> |
07 | < 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" /> |
08 | < date.created >2010-01-08T23:44:16Z</ date.created > |
09 | < user.createdby id = "1" href = "http://192.168.168.110/@api/deki/users/1" > |
10 | < nick >Admin</ nick > |
11 | < username >Admin</ username > |
12 | < email >melder@mindtouch.com</ email > |
13 | < hash.email >637b79dca5c8ebdc4347bccca42d3487</ hash.email > |
14 | < uri.gravatar >http://www.gravatar.com/avatar/637b79dca5c8ebdc4347bccca42d3487</ uri.gravatar > |
15 | </ user.createdby > |
16 | < revisions count = "3" totalcount = "3" href = "http://192.168.168.110/@api/deki/files/9/revisions" /> |
17 | < page.parent id = "51" href = "http://192.168.168.110/@api/deki/pages/51?redirects=0" > |
18 | < uri.ui >http://192.168.168.110/Jean_Luc_Picard</ uri.ui > |
19 | < title >Jean Luc Picard</ title > |
20 | < path >Jean_Luc_Picard</ path > |
21 | < namespace >main</ namespace > |
22 | </ page.parent > |
23 | < properties count = "1" href = "http://192.168.168.110/@api/deki/files/9/properties" > |
24 | < 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.r1_ts2010-01-11T20:26:04Z" > |
25 | < 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 5</ contents > |
26 | < date.modified >2010-01-11T20:26:04Z</ date.modified > |
27 | < user.modified id = "1" href = "http://192.168.168.110/@api/deki/users/1" > |
28 | < nick >Admin</ nick > |
29 | < username >Admin</ username > |
30 | < email >melder@mindtouch.com</ email > |
31 | < hash.email >637b79dca5c8ebdc4347bccca42d3487</ hash.email > |
32 | < uri.gravatar >http://www.gravatar.com/avatar/637b79dca5c8ebdc4347bccca42d3487</ uri.gravatar > |
33 | </ user.modified > |
34 | </ property > |
35 | </ properties > |
36 | </ file > |
Notes
- Running the command on an existing description will overwrite it.