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 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:


This page may have a more recent version on pmwiki.org: PmWiki:EditingAPI, and a talk page: PmWiki:EditingAPI-Talk.

PmWiki Developer