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 authid is normally used for
this together with the field authpw.
|
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.
I think this "note" should be accompanied with something that's well
specified, so as to make it easier for an external script to handle
this situation. /Christian
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.
I think some formal method is needed to report that a save has been
blocked. The reason for the block might be a requirement for an author
name, or that blocklist don't like it. There should be an API to detect
this in any case. /Christian
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.
Sure, I can probably add that somewhere -- likely a comment in the <head>
section.
The other thing to look for is that a successful post always results in a
redirect (i.e., status 302 or 301 or something), while an unsuccessful
post results in a 200.
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
- Smc? - Added file upload details and real-world examples using curl.
Categories: PmWiki Developer
