users/{userid}/properties (POST)

Overview

Create a user property

REST Method: POST
Method Access: public

Uri Parameters

Name	Type	Description
userid	string	either an integer user ID, "current", or "=" followed by a double uri-encoded user name

Query Parameters

Name	Type	Description
authenticate	bool?	Force authentication for request (default: false)
abort	{never, modified, exists}?	Specifies condition under which to prevent the creation; default is exists.
redirects	int?	If zero, do not follow page redirects.
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 could not be found

Message Format

Input is an HTTP request containing a Slug header with the name of the property, a Content-Type header, a Content-Length, and the pro

POST /@api/deki/users/x/properties?description=description of foo
Host: wikihost
Slug: foo
Content-Type: image/jpg
Content-Length: 12345

... data here ...

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.
A user may only read and write their own properties. Admins can read/write anyones users properties.

C# Sample: Add User Property

The following code authenticates and creates a new 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")
 .WithHeader("Slug", "foo")
 .With("description", "initial value")
 .Post(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.r1_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>initial value</change-description>
</property>

Curl Sample: Add User Property

The following command adds a user property with property name "foo" and pairs it with the data from file "bar". The user name is "user".

Sample Code

curl -u username:password -H "Content-Type: text/plain" -H "Slug: foo" -d @bar -i http://mindtouch.address/@api/deki/users/=user/properties

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.
-d @file: Specifies a POST request and the data file to send.
-H: Replaces or appends an HTTP header. The "Slug" header designates the property name. 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.

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.

Example

We want to create a simple text property for the user Batman. The property name is "alterego" and the value is "Bruce Wayne", as outlined in "userprop.txt".

userprop.txt

Content-Type: text/plain

Bruce Wayne

Sample Code

curl -u username:password -H "Content-Type: text/plain" -H "Slug: alterego" -d @userprop.txt -i http://192.168.168.110/@api/deki/users/=Batman/properties

HTTP Response Headers

HTTP/1.1 200 OK
Date: Tue, 12 Jan 2010 01:10:45 GMT
Server: Dream-HTTPAPI/1.7.2.17433
X-Deki-Site: id="default"
Content-Type: application/xml; charset=utf-8
Content-Length: 680
Via: 1.1 dekiwiki

HTTP Response Body

Content-Type: application/xml

<?xml version="1.0"?>
<property name="alterego" href="http://192.168.168.110/@api/deki/users/4/properties/alterego/info" etag="35.r1_ts2010-01-12T01:10:44Z">
  <contents type="text/plain" size="11" href="http://192.168.168.110/@api/deki/users/4/properties/alterego">Bruce Wayne</contents>
  <date.modified>2010-01-12T01:10:44Z</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

In order for properties to be displayed in "Page Properties" pages, the property name must be prefixed with "urn:custom.mindtouch.com#", otherwise it will remain hidden.
The easiest way to view properties if they do not appear in the UI is by accessing the XML file for the page properties. For example, the XML for the above path is <http://192.168.168.110/@api/deki/use...man/properties>.