pages/{pageid}/properties (PUT)

Overview

Perform changes on multiple page properties

REST Method: PUT
Method Access: public

NOTE: Expert sets a limit of 1,000 properties per page.

Uri Parameters

Name	Type	Description
pageid	string	either an integer page ID, "home", or "=" followed by a double uri-encoded page path

Query Parameters

Name	Type	Description
redirects	int?	If zero, do not follow page redirects.
authenticate	bool?	Force authentication for request (default: false)

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 page could not be found

Message Format

Input is a list of property xml blocks. Only text values are allowed to be modified via this feature. To modify a non-text property value, use PUT: pages/{pageid}/properties/{key} instead. Properties are deleted if no contents node is provided. An etag is not required for deleting properties. Note that the language element is accepted for backwards compatibility.

<properties>
 <property name="{text}" etag="{text}">
  <contents type="{text}">{text}</contents>  
  <change-description>{text}</change-description>
 </property>
 <property name="{text}"/>
 <language>{language}</language>
</properties>

Response is a list of the standard property xml blocks as well as any error blocks.

<properties count="{int}" href="{uri}">
 <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>
 <property name="{text}">
    <status code="{int}">
      <error>
        <status>{int}</status>
        <title>{text}</title>
        <message>{text}</message>
        <uri>{uri}</uri>
      </error>
    </status>
 </property>
</properties>

Implementation Notes

This feature supports modifying the page language with the 'language' element. It must be a valid language code such as "en", "de", "zh-tw" etc. An empty language indicates culture invariant.
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.

C# Sample: Modifying Page Properties

The following code example sets the language of the home page to German:

Sample Code

Plug p = Plug.New("http://deki-hayes/@api/deki");
p.At("users", "authenticate").WithCredentials("admin", "password").Get();
XDoc propertiesDoc = new XDoc("properties").Elem("language", "de");
p.At("pages", "home", "properties").Put(propertiesDoc);

Authentication is performed and a property is created named "myprop" for the page 'My/Test/Page'. Using the batch property update feature, "myprop" is updated with a new value with the current value's etag. A non existent property "propertyToDelete" is attempted to be deleted by not specifying a new content value.

Plug p = Plug.New("http://devwiki/@api/deki");
p.At("users", "authenticate").WithCredentials("sysop", "password").Get();

XDoc myPropResponse = p.At("pages", "=My%252fTest%252fPage", "properties")  .WithHeader("Slug", "myprop")
 .Post(DreamMessage.Ok(MimeType.TEXT_UTF8, "initial value")).AsDocument();

XDoc body = new XDoc("properties");
body.Start("property").Attr("name", "myprop").Attr("etag", myPropResponse["/property/@etag"].AsText)
 .Start("contents").Attr("type", "text/plain").Value("new value for property").End()
 .Elem("description", "description of change")
 .End();
body.Start("property").Attr("name", "propertyToDelete").End();

XDoc response = p.At("pages", "=My%252fTest%252fPage", "properties") .Put(body).AsDocument();

Sample Response from executing Code

<properties count="1" href="http://devwiki/@api/deki/pages/42/properties">
  <property name="myprop" href="http://devwiki/@api/deki/pages/42/properties/myprop/info" etag="4465.r2_ts2009-03-20T23:52:50Z">
    <contents type="text/plain" href="http://devwiki/@api/deki/pages/42/properties/myprop">new value for property</contents>
    <date.modified>2009-03-20T23:52:50Z</date.modified>
    <user.modified id="1" href="http://devwiki/@api/deki/users/1">
      <nick>Sysop</nick>
      <username>Sysop</username>
    </user.modified>
    <change-description>description of change</change-description>
    <status code="200" />
  </property>
  <property name="propertyToDelete">
    <status code="400">
      <error>
        <status>400</status>
        <title>Bad Request</title>
        <message>The property 'propertyToDelete' does not exist and cannot be deleted.</message>
        <uri>http://devwiki/@api/deki/pages/42/properties</uri>
      </error>
    </status>
  </property>
</properties>

Implementation notes

Add notes about requirements or config values

Curl Sample: Modifying Page Properties

The following command attaches the properties listed in "properties.xml" to page "test".

Sample Code

curl -u username:password -H "Content-Type: application/xml" -T properties.xml -i http://mindtouch.address/@api/deki/pages/=test/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.
-H: Adds a header or modifies an existing one. In this case, since an xml document is being sent, the content type must be set to "application/xml". The server will not accept the request otherwise.
-T file: Specifies the .xml file that contains the user property data.
-i: Includes the HTTP response header in the output. Useful for debugging.

Example

Let's modify some properties attached to Jean Luc Picard's page. One property, "rank", already exists as implemented here.

jlpprop.xml

Content-Type: application/xml

<properties>

    <!-- Add a couple properties -->

    <property name="isbald">
	<contents type="text/plain">yes</contents>
    </property>
    <property name="nemesis">
	<contents type="text/plain">the Borg</contents>
    </property>

    <!-- Remove a property, to do this omit contents element -->

    <property name="rank"/>

</properties>

Command Line

curl -u admin:password -H "Content-Type: application/xml" -T jlpprop.xml -i http://192.168.168.110/@api/deki/pages/=Jean%2520Luc%2520Picard/properties

HTTP Response Headers

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

HTTP Response Body

Content-Type: application/xml

<?xml version="1.0"?>
<properties count="3" href="http://192.168.168.110/@api/deki/pages/51/properties">
  <property name="isbald" href="http://192.168.168.110/@api/deki/pages/51/properties/isbald/info" etag="42.r1_ts2010-01-13T22:35:21Z">
    <contents type="text/plain" size="3" href="http://192.168.168.110/@api/deki/pages/51/properties/isbald">yes</contents>
    <date.modified>2010-01-13T22:35: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>
    <status code="200"/>
  </property>
  <property name="nemesis" href="http://192.168.168.110/@api/deki/pages/51/properties/nemesis/info" etag="43.r1_ts2010-01-13T22:35:22Z">
    <contents type="text/plain" size="8" href="http://192.168.168.110/@api/deki/pages/51/properties/nemesis">the Borg</contents>
    <date.modified>2010-01-13T22:35:22Z</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>
    <status code="200"/>
  </property>
  <property name="rank" href="http://192.168.168.110/@api/deki/pages/51/properties/rank/info" etag="32.r2_ts2010-01-13T22:35:22Z">
    <contents type="text/plain" size="7" href="http://192.168.168.110/@api/deki/pages/51/properties/rank">captain</contents>
    <date.modified>2010-01-13T22:35:22Z</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>
    <user.deleted 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.deleted>
    <date.deleted>2010-01-13T22:35:22Z</date.deleted>
    <status code="200"/>
  </property>
</properties>

Notes

To view all properties attached to a specific page, fetch the raw XML data that represents that page. In this case, the path is <http://192.168.168.110/@api/deki/pag...ard/properties>.
The page path is double encoded. In the above example, spaces in "Jean Luc Picard" are replaced with %2520.