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=202411138133
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