files/{fileid}/properties/{key} (PUT)

Overview

Update an existing attachment property

REST Method: PUT
Method Access: public

Uri Parameters

Name	Type	Description
key	string	A unique identifier for a property that is obtained through GET:files/{fileid}/properties
fileid	int	identifies a file by ID

Query Parameters

Name	Type	Description
description	string?	Description of property
etag	string?	Etag of the current version of the property. Can alternatively be provided via ETag header.
authenticate	bool?	Force authentication for request (default: false)
redirects	int?	If zero, do not follow page redirects.
abort	{never, modified, exists}?	Specifies condition under which to prevent the update; default is modified.

Return Codes

Name	Value	Description
OK	200	The request completed successfully
Bad Request	400	Invalid input parameter or request body
Forbidden	403	UPDATE access is required
Not Found	404	Requested file and/or property could not be found

Message Format

Response is the standard property XML

<property name="{text}" href="{uri}" etag="{text}">
  <contents type="{text}" href="{uri}">{text}</contents>
  <date.modified>{date}</date.modified>
  <user.modified id="{int}" href="{uri}">
    <nick>{text}</nick>
    <username>{text}</username>
  </user.modified>
  <change-description>{text}</change-description>
</property>

Implementation Notes

The response XML will contain the contents text only for text based mimetypes with values less than 2048 chars in length. Otherwise the contents is available at the URI pointed to by property/contents/@href.
UPDATE rights to the parent page of a file is necessary to create or change a file property value. READ access is required to get the properties and its metadata.

C# Sample: Modify a File Property

The following code authenticates and modifies a file property named 'foo' with a text value. A description of the change is set as well.

Sample Code


Plug p = Plug.New("http://devwiki/@api/deki"); 
p.At("users", "authenticate")
 .WithCredentials("sysop", "password").Get(); 
p.At("files", "42", "properties", "foo")
 .WithHeader(DreamHeaders.ETAG, "4463.r1_ts2009-03-19T20:00:15Z")
 .With("description", "correcting the value") 
 .Put(DreamMessage.Ok(MimeType.TEXT_UTF8, "My Value"));

Sample Response from executing Code

<property name="foo" href="http://devwiki/@api/deki/files/42/properties/foo/info" etag="4463.r2_ts2009-03-20T22:48:15Z">
  <contents type="text/plain; charset=utf-8" href="http://devwiki/@api/deki/files/42/properties/foo">My Value</contents>
  <date.modified>2009-03-20T22:48:15Z</date.modified>
  <user.modified id="1" href="http://devwiki/@api/deki/users/1">
    <nick>Sysop</nick>
    <username>Sysop</username>
  </user.modified>
  <change-description>correcting the value</change-description>
</property>

Implementation notes

Add notes about requirements or config values

Curl Sample: Modify a File Property

The following command modifies file property "foo" of file with file ID = 1 and pairs the file "bar" with the property.

Sample Code

curl -u username:password -H "Content-Type: text/plain" -H "Etag: xxx" -T bar -i http://mindtouch.address/@api/deki/files/1/properties/foo

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 file: Specifies a PUT request and the file to send.
-H: Replaces or appends an HTTP header. The "Content-Type" header specifies the MIME type of the value attached to the property.
-i: Includes the HTTP response header in the output. Useful for debugging.

Permissions

UPDATE permission is required to execute above command. Otherwise, a 403 HTTP response (Forbidden) will be returned.

MIMEs

Properties can contain any type of file, therefore it is important to specify the correct MIME when creating a property. For instance, a text property will require a text/plain header, xml will require application/xml header, a jpeg image will require image/jpg header, and so on.

ETag

An ETag is required to ensure the property being modified is in its most recent revision. If there is an ETag mismatch, the server will return a 409 HTTP response (Conflict). There are two ways to pass ETags to the server. The first, adding an ETag HTTP header, is shown above. ETags can also be passed via appending a parameter to the end of the path. The following is equivalent to the above sample:

curl -u username:password -H "Content-Type: text/plain" -T bar -i http://mindtouch.address/@api/deki/pages/=test/properties/foo?etag=xxx

Example

A specific file has been revised and thus we need to make a change to a property. The file (file ID = 9) is now of type video, so the "type" property created needs to be updated. The new file property value is written in fprop.txt.

fprop.txt

Content-Type: text/plain

video

Sample Code

curl -u admin:password -H "Content-Type: text/plain" -T fprop.txt -i http://192.168.168.110/@api/deki/files/9/properties/type?etag=49.r1_ts2010-01-15T01:50:28Z

HTTP Response Headers

HTTP/1.1 200 OK
Date: Fri, 15 Jan 2010 22:11:23 GMT
Server: Dream-HTTPAPI/1.7.2.17433
X-Deki-Site: id="default"
Content-Type: application/xml; charset=utf-8
Content-Length: 661
Via: 1.1 dekiwiki

HTTP Response Body

Content-Type: application/xml

<?xml version="1.0"?>
<property name="type" href="http://192.168.168.110/@api/deki/files/9/properties/type/info" etag="49.r2_ts2010-01-15T22:11:21Z">
  <contents type="text/plain" size="5" href="http://192.168.168.110/@api/deki/files/9/properties/type">video</contents>
  <date.modified>2010-01-15T22:11:21Z</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>

Notes

To view the list of properties attached to a file (including property ETags), access the file properties raw XML data. For example, for the above path, the file's page XML data would be located at <http://192.168.168.110/@api/deki/files/9/properties>.