pages/{pageid}/contents (POST)

Overview

Update contents of a page

REST Method: POST
Method Access: public

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
ordered	bool?	If this is a new hierarchy make it ordered, and put this page at the front
restriction	string?	Optionally set the restriction of the page
importtime	string?	If this is an import, the edit timestamp of the imported content (yyyyMMddHHmmss or yyyy-MM-ddTHH:mm:ssZ)
overwrite	bool?	New page revision is created when no changes are detected when overwrite is true (default: false)
reltopath	string?	Page used for path normalization. Ignored if relto parameter is defined. (default: none)
relto	int?	Page used for path normalization (default: none)
abort	{never, modified, exists}?	specifies condition under which to prevent the save; default is never
xpath	string?	identifies the portion of the page to update; this parameter is ignored if section is specified
section	int?	the section number. If zero, append as a new section
title	string?	the display title (default: use existing title or determine from page path.)
comment	string?	the edit comment
edittime	string	the previous revision's edit timestamp (yyyyMMddHHmmss) or "now" to bypass concurrent edit check
authenticate	bool?	Force authentication for request (default: false)
redirects	int?	If zero, do not follow page redirects.
tidy	{remove, convert}?	Determines if invalid content is converted to text or removed (default: 'convert')

Return Codes

Name	Value	Description
OK	200	The request completed successfully
Bad Request	400	Invalid input parameter or request body
Forbidden	403	Update access to the page is required
Not Found	404	Requested page could not be found

Message Format

Input:
Content-type=text/plain

Output:

<edit status="{success|conflict}">
    <page id="{int}" href="{uri}">
        <title>{text}</title> 
        <path>{text}</path> 
    </page>
    <page.base id="{int}" revision="{int}" href="{uri}">
        <title>{text}</title> 
        <path>{text}</path> 
        <date.edited>{date}</date.edited>
        <user.author id="{int}" href="{uri}">
            <nick>{text}</nick> 
            <username>{text}</username> 
            <email>{text}</email> 
        </user.author>
        <description>{text}</description> 
        <contents type="{contenttype}" href="{uri}" /> 
    </page.base>
    <page.overwritten id="{int}" revision="{int}" href="{uri}">
        <title>{text}</title> 
        <path>{text}</path> 
        <date.edited>{date}</date.edited> 
        <user.author id="{int}" href="{uri}">
            <nick>{text}</nick> 
            <username>{text}</username> 
            <email>{text}</email> 
        </user.author>
        <description>{text}</description> 
        <contents type="{contenttype}" href="{uri}" /> 
    </page.overwritten>
</edit>

Implementation Notes

If the page does not exist, a new page is created. Otherwise, the existing page is updated.

Use the Abort parameter to control edit conflict behavior. Abort=exists specifies that the save should abort if the page already exists. Similarly, Abort=modified specifies that the save should abort if the page has been modified since the Edittime parameter. Abort=never always allows the save to occur; the system makes no attempt to merge edit conflicts and simply overwrites the existing content. If an edit conflict is detected (ie. someone else edited the page since the value specified in the Edittime parameter), the edit status is set to "conflict" and the page.base/page.overwritten elements are populated. The page.base element displays the revision upon which the changes in the current save were based. The page.overwritten element displays the page revision containing the overwritten content.

It is possible to update a portion of an existing page using either the Section or XPath parameters. The Section parameter contains the integer section number to update. Everything within the specified section is replaced, including the section heading itself. Section=0 specifies to append the new content to the end of the document. The XPath parameter identifies a document node to replace. Refer here for more information on XPath syntax.

Note

The edittime parameter has to be supplied when updating a page!

C# Code Sample: Dekiscript function to create a page

C# native API to create a dekiscript function that can call the Expert API to create a page

Create a dekiscript function that can create pages

Sample Code

[DekiExtFunction(Description = "trying to call a dream API (actually to create a wiki page ")]
public XDoc xCreatePage([ DekiExtParam("authtoken", true)] string authtoken, [DekiExtParam("path to put ", true)] string path,
    [DekiExtParam("pagename", true)] string pagename, [DekiExtParam("pagename", true)] string contentstring) {
    if(contentstring == null) contentstring = "";
       
    //make it so an empty page is created if no content is passed in.
    Plug p = Plug.New(this.Config["uri.deki"].AsUri);
    DreamMessage msg = DreamMessage.Ok(MimeType.TEXT, contentstring);
    var res = p.At("pages", "=" + System.Web.HttpUtility.UrlEncode(path + pagename), "contents")
            .With("authtoken", authtoken)
            .With("abort", "never")
            .With("edittime", DateTime.Now)
            .Post(msg);
    return res.ToDocument();
}

Sample Response from executing Code

<edit status="success"> <page id="892" href="http://mydomain/@api/deki/pages/892redirects=0"> <uri.ui>http://mydomain/Information_Technology/mytestpage2</uri.ui> <title>mytestpage2</title><path>Information_Technology/mytestpage2</path> <namespace>main</namespace></page></edit>

C# Code Sample: Create a page

The following code example creates a new page called "Subpage 1" under the page called "Page Title"; it will fail if the page already exists. The new page contents contains two sections:

Sample Code

Plug p = Plug.New("http://deki-hayes/@api/deki");
p.At("users", "authenticate").WithCredentials("admin", "password").Get();
DreamMessage msg = DreamMessage.Ok(MimeType.TEXT, "<h2>Section 1</h2>Section 1 text<h2>Section2</h2>Section 2 text");
p.At("pages", "=Page_Title%252fSubpage_1", "contents").With("abort", "exists").Post(msg);

Sample Response from executing Code

<edit status="success">
    <page id="84" href="http://deki-hayes/@api/deki/pages/84">
        <title>Subpage 1</title> 
        <path>Page_Title/Subpage_1</path> 
    </page>
</edit> button in the toolbar

Curl Code Sample: Create a Page

The following curl command creates a page named "test" with the data in foo.txt as the page's body.

Sample Code

curl -u username:password -d @foo.txt -i http://mindtouch.address/@api/deki/pages/=test/contents

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 the .txt file that contains the page body data.
-i: Includes the HTTP response header in the output. Useful for debugging.

Example

The following curl command will create a page about our favorite captain of the U.S.S. Enterprise, Jean Luc Picard. "picard.txt" contains the body of the document.

picard.txt

<h2>Captain Jean Luc Picard</h2>
Of the U.S.S. Enterprise<br><br>

<i>Engage!</i>

Sample Code

curl -u username:password -d @picard.txt -i http://192.168.168.110/@api/deki/pages/=Jean%2520Luc%2520Picard/contents

HTTP Response Headers

HTTP/1.1 200 OK
Date: Wed, 06 Jan 2010 22:42:06 GMT
Server: Dream-HTTPAPI/1.7.0.16080
X-Deki-Site: id="default"
Content-Type: application/xml; charset=utf-8
Content-Length: 252
Via: 1.1 dekiwiki

HTTP Response Body

Content-Type: application/xml

<?xml version="1.0"?>
<edit status="success">
  <page id="51" href="http://192.168.168.110/@api/deki/pages/51?redirects=0">
    <uri.ui>http://192.168.168.110/Jean_Luc_Picard</uri.ui>
    <title>Jean Luc Picard</title>
    <path>Jean_Luc_Picard</path>
    <namespace>main</namespace>
  </page>
</edit>

Notes

The request body needs to be formatted in HTML. Only the contents found inside of the <body> can be part of the request.
The page path is double encoded. In the above example, spaces in "Jean Luc Picard" are replaced with %2520.
Attempting to create a page where one already exists will result in a 404 HTTP Response (Not Found).

Curl Code Sample: Editing an existing Page

The following Curl command replaces the contents of page named "test" with the contents in file foo.txt

Sample Code

curl -u admin:password -d @foo.txt -i http://mindtouch.address/@api/deki/pages/=test/contents?edittime=202412223181

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 the .txt file that contains the page body data.
-i: Includes the HTTP response header in the output. Useful for debugging.

Example

foo.txt

<h2> test </h2>
This is the test file that will replace the original<br>

Command:

curl -u user:password -d @foo.txt http://mindtouch.address/@api/deki/pages/=test/contents?edittime=20100914123000

This command loads foo.txt to replace the current page called "test". The edittime parameter is necessary for editing a page, the tiestamp must be newer than when the page was created. It is specified using the following format: YYYYMMDDhhmmss

HTTP Response Headers

HTTP/1.1 200 OK
Date: Tue, 14 Sep 2010 19:26:47 GMT
Server: Dream-HTTPAPI/2.1.1.21089
X-Data-Stats: request-time-ms=285; mysql-queries=10; mysql-time-ms=223; cache-ratio=3.50; cache-hit=14; cache-miss=-10; cache-del=1; cache-ins=10;
X-Deki-Site: id="default"
Content-Type: application/xml; charset=utf-8
Content-Length: 237
Via: 1.1 dekiwiki

HTTP Response Body

Content-Type: application/xml
<edit status="success">
<page id="663" revision="1" href="http://192.168.168.104/@api/deki/pages/663?redirects=0">
<uri.ui>http://192.168.168.104/test2</uri.ui>
<title>test2</title>
<path>test2</path>
<namespace>main</namespace>
</page>
</edit>

Notes

The page path is double encoded. In the above example, spaces in "Jean Luc Picard" are replaced with %2520.
You must specify the edittime parameter in the following format: YYYYMMDDhhmmss