users/{userid}/properties/{key} (PUT)

Overview

Update an existing user property

Uri Parameters

Name Type Description
userid string either an integer user ID, "current", or "=" followed by a double uri-encoded user name
key string A unique identifier for a property that is obtained through GET:users/{userid}/properties

Query Parameters

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

Return Codes

Name Value Description
OK 200 The request completed successfully
Bad Request 400 Invalid input parameter or request body
Forbidden 403 ADMIN access is required to access other user's properties
Not Found 404 Requested user 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

C# Sample: Modify a User Property

The following code authenticates and modifies a user 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("users", "current", "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/users/1/properties/foo/info" etag="4463.r2_ts2009-03-20T22:48:15Z">
  <contents type="text/plain; charset=utf-8" href="http://devwiki/@api/deki/users/1/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 User Property

The following command modifies user property "foo" of user "user" and pairs the file contents of "bar" with the property.

Sample Code

curl -u admin:password -H "Content-Type: text/plain" -H "Etag: xxx" -T bar -i http://mindtouch.address/@api/deki/users/=user/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

ADMIN 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 admin:password -H "Content-Type: text/plain" -T bar -i http://mindtouch.address/@api/deki/users/=user/properties/foo?etag=xxx

Example

Batman has moved to Metropolis, so we want to update his location. The location property already exists and was created here. His new location is listed in file "locprop.txt".

locprop.txt

Content-Type: text/plain

Metropolis

Sample Code

curl -u admin:password -H "Content-Type: text/plain" -H "Etag: 37.r1_ts2010-01-12T23:51:20Z" -T locprop.txt -i http://192.168.168.110/@api/deki/users/=Batman/properties/location

HTTP Response Headers

Date: Wed, 13 Jan 2010 00:50:50 GMT
Server: Dream-HTTPAPI/1.7.2.17433
X-Deki-Site: id="default"
Content-Type: application/xml; charset=utf-8
Content-Length: 679
Via: 1.1 dekiwiki

HTTP Response Body

Content-Type: application/xml

<?xml version="1.0"?>
<property name="location" href="http://192.168.168.110/@api/deki/users/4/properties/location/info" etag="37.r2_ts2010-01-13T00:50:50Z">
  <contents type="text/plain" size="10" href="http://192.168.168.110/@api/deki/users/4/properties/location">Metropolis</contents>
  <date.modified>2010-01-13T00:50:50Z</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