Editing API
This page documents the API for modifying PmWiki pages via the wiki engine (i.e. via pmwiki.php
) using curl or HTTP.
Sending a request to write to a page
The following fields may occur in a request to write to a wiki page.
Field=<value> | Example | Note |
n=<Group>.<PageName>
| n=PmWiki.SandBox
| Mandatory. The name of the destination page of the write request. |
text=<page-text>
| text=Hello%20World
| Mandatory. The urlencoded text that is requested to be written to the page. |
action=edit
| action=edit
| Mandatory. One of the two fields that signals that this is a write request. |
post=1
| post=1
| Mandatory. The other of the two fields that signals that this is a write request. |
author=<author>
| author=alicia
| Usually not required. If supplied, <author> is considered the name to be assocated
with this change. |
diffclass=minor
| diffclass=minor
| Not required.
If present, this field and argument indicates that the change is a minor change. |
authid=<user-name>
| authid=alicia
| Usually not required. For a password protected page, the client must either already have been
previously authenticated (via a PHP session cookie), or otherwise send
the appropriate credentials. The field |
authpw=<password>
| authpw=quick
| Usually not required, see authid=<user-name> above.
|
basetime=<nnnnn>
| basetime=1312020116
| Not mandatory. Note that if this field is not present, there will be no
checking for simultaneous edits. See further down for more details. |
Summarizing the requirements to post an update to a page.
Writing a page to the wiki via the wiki engine, i.e. via pmwiki.php
is
done via an HTTP POST
request. At a minimum, the following fields are
required:
n=<Group>.<PageName>
text=<text to be posted>
action=edit
post=1
The two fields action=edit
and post=1
together signals that the
request is to write the content of the field text
to the the destination
page, i.e. as specified by the field n
.
Additional fields such as author=<author>
and diffclass=minor
can be
given, see the table of fields for an explanation.
If the page is password protected, the browser must either have been previously authenticated (via a PHP session cookie) or otherwise send the appropriate credentials to allow edit access to the page. Normally the credentials are given by the 'authpw' and 'authid' fields:
authid=<user-name>
authpw=<password>
Simultaneous edits are handled by the field 'basetime
'. When a browser
requests an edit form using ?action=edit
, PmWiki includes a hidden field
'basetime
' in the edit form that holds the time the form was sent.
When the form is submitted, if the last modification time of the page is greater than the basetime in the form, we know that the page changed somehow after the author requested the edit form. (The basetime also tells PmWiki which version of the page was "current" when the edit form was requested, so it can figure out how to merge the changes together.)
If a page is changed after a form's basetime, then instead of saving the page PmWiki sends back a new edit form with any merged changes and a note to the author to review the page for conflicts and submit again.
If a client sends a post request that doesn't include a 'basetime
'
field, then no simultaneous edit checking is performed, and the contents of
the field 'text
' replace any existing content.
A successful request to save a page generally results in a 302 HTTP response, telling the browser to view the (newly saved) page. If a request to save a page fails, generally PmWiki returns a new edit form along with messages indicating why the page could not be saved.
Christian's questions:
- Can authpw/authid be used to satisfy Apaches Basic Authenticiation as well?
Sending a request to upload a file to a page
The following fields may occur in a request to upload a file attachment to a wiki page.
Field=<value> | Example | Note |
n=<Group>.<PageName>
| n=PmWiki.SandBox
| Mandatory. The name of the destination page of the write request. |
action=postupload
| action=postupload
| Mandatory. One of the two fields that signals that this is an upload file request. |
uploadfile=<filename.ext>
| uploadfile=/c/myfile.gif
| Mandatory. The name of the file to be uploaded in the POST request sent to PmWiki. |
upname=<filename.ext>
| upname=altfilename.gif
| Optional. The uploaded file will be called this name within PmWiki. |
Real-world examples
Using curl
Using curl to create a wiki page one would:
curl -d "?n=Main.WikiSandbox&text=TestingWiki&action=edit&post=1&author=AuthorName" http://localhost/pmwiki.php/Main/WikiSandbox
Note: the value for 'text' is assumed to already be urlencoded e.g. %20 for space.
Using curl to upload a file called testing.txt to the SandBox page one would:
curl -F n=Main.WikiSandbox -F action=postupload -F uploadfile=@/c/testing.txt -F upname=alt-name.txt http://localhost/pmwiki.php/Main/WikiSandbox
Note: The AT (@) character before the file is required.
Notification of problems
In response to a post by Christian, Patrick wrote on 2006-03-09
> As an aside, I was using pmwiki-mode for Emacs, which unfortunately meant > that I got no warning that the the edit post was blocked :-( > > That finally leads me to the following suggestion: Could PmWiki output > some kind of error message relatively early in the HTML which you get > after an unsuccessful post? This message could simply be an embedded > HTML-comment as far as I'm concerned.
Christian's comment:
- A redirect does unfortunately not give an indication as to why the save didn't work.
Timo's comment:
- If you want to update a wiki page, you can fetch the source using action=source and then reupload.
Accessing a password protected page
From Patrick in post on the PmWiki user's list on 2007-06-28.
> If you're using curl as a command-line tool, try the -d option: > > curl -d authpw=banana http://my.wiki.org/ProtectedGroup.DataPage > > This generates a POST request for the page, exactly as if someone > had filled in the authorization form.
Contributors
Categories: PmWiki Developer
This page may have a more recent version on pmwiki.org: PmWiki:EditingAPI, and a talk page: PmWiki:EditingAPI-Talk.