pages/{pageid}/properties (POST)
Overview
Create a page property
- REST Method: POST
- 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 |
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 |
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 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/pages/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.
- 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# Code Sample: Add Page Property
The following code authenticates and creates a new page property named 'foo' with a text value for the page 'My/Test/Page'. 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") .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/pages/42/properties/foo/info" etag="4463.r1_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>initial value</change-description> </property>
Curl Code Sample: Add Page Property
The following command adds a page property to page "test" with property name "foo" and pairs it with the data from file "bar".
Sample Code
curl -u username:password -H "Content-Type: text/plain" -H "Slug: foo" -d @bar -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.
- -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 Jean Luc Picard's page. The property name will be "rank" and the value will be "captain", as outlined in "jlpprop.txt".
jlpprop.txt
Content-Type: text/plain
captain
Sample Code
curl -u username:password -H "Content-Type: text/plain" -H "Slug: rank" -d @jlpprop.txt -i http://192.168.168.110/@api/deki/pages/=Jean%2520Luc%2520Picard/properties
HTTP Response Headers
HTTP/1.1 200 OK Date: Mon, 11 Jan 2010 23:52:16 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="32.r1_ts2010-01-11T23:52:16Z"> <contents type="text/plain" size="7" href="http://192.168.168.110/@api/deki/pages/51/properties/rank">captain</contents> <date.modified>2010-01-11T23:52:16Z</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
- The page path is double encoded. In the above example, spaces in "Jean Luc Picard" are replaced with %2520.
- 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 Jean Luc Picard page is <http://192.168.168.110/@api/deki/pag...ard/properties>.