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.