pages/{pageid}/properties/{key} (PUT)
Overview
Update an existing page property
- REST Method: PUT
- Method Access: public
NOTE: Expert sets a limit of 1,000 properties per page.
Uri Parameters
Name | Type | Description |
key | string | A unique identifier for a property that is obtained through GET:pages/{pageid}/properties |
pageid | string | either an integer page ID, "home", or "=" followed by a double uri-encoded page path |
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. |
description | string? | Description of property |
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. |
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 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 page is necessary to create or change a property value. READ access is required to get the properties and its metadata.
C# Sample: Modify a Page Property
The following code authenticates and modifies a page 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("pages", "=My%252fTest%252fPage", "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/pages/42/properties/foo/info" etag="4463.r2_ts2009-03-20T22:48:15Z"> <contents type="text/plain; charset=utf-8" href="http://devwiki/@api/deki/pages/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 Page Property
The following command modifies page property "foo" of page "test" 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/pages/=test/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
Jean Luc Picard has been promoted to admiral. The page property rank, created here, needs to be updated. The rank property value is located in file "jlpprop.txt".
jlpprop.txt
Content-Type: text/plain
Admiral
Sample Code
curl -u admin:password -H "Content-Type: text/plain" -T jlpprop.txt -i http://192.168.168.110/@api/deki/pages/=Jean%2520Luc%2520Picard/properties/rank?etag=44.r2_ts2010-01-13T22:59:20Z
HTTP Response Headers
HTTP/1.1 200 OK Date: Wed, 13 Jan 2010 23:04:18 GMT Server: Dream-HTTPAPI/1.7.2.17433 X-Deki-Site: id="default" Content-Type: application/xml; charset=utf-8 Content-Length: 665 Via: 1.1 dekiwiki
HTTP Response Body
Content-Type: application/xml
<?xml version="1.0"?> <property name="rank" href="http://192.168.168.110/@api/deki/pages/51/properties/rank/info" etag="44.r3_ts2010-01-13T23:04:18Z"> <contents type="text/plain" size="7" href="http://192.168.168.110/@api/deki/pages/51/properties/rank">captain</contents> <date.modified>2010-01-13T23:04:18Z</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 page (including property ETags), access the page properties raw XML data. For example, for the above path, Jean Luc Picard's page XML data would be located here <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.