Fossil

JSON API: /wiki
Login

JSON API: /wiki

(⬑JSON API Index)

Jump to:

Page List

Returns a list of all pages, not including their content (which can be arbitrarily large).

Status: implemented 201109xx

Required privileges: "j" or "o"

Request: /json/wiki/list

Options:

Response payload: format depends on "verbose" option

Non-verbose mode:

["PageName1",..."PageNameN"]

In verbose mode:

[{
"name":"Apache On Windows XP",
"uuid":"a7e68df71b95d35321b9d9aeec3c8068f991926c",
"user":"jeffrimko",
"timestamp":1310227825,
"size":793 /* in bytes */
},...]

The verbose-mode output is the same as the /json/wiki/get output, but without the content. The size property of each reflects the byte length of the raw (non-HTMLized) page content.

Potential TODOs:

Fetch a Page

Fetches a single wiki page, including content and significant metadata.

Status: implemented 20110922, but response format may change.

Required privileges: "j" or "o"

Request:

Response payload example:

{
"name": "Fossil",
"uuid": "...hex string...",
"parent": "uuid of parent (not set for first version of page)",
"user": "anonymous",
"timestamp": 1286143975,
"size": 1906, /* In bytes, not UTF8 characters!
                 Affected by format option! */
"content": "..."
}

FIXME: it's missing the mimetype (that support was added to fossil after this was implemented).

If given no page to load, or if asked to get a page which does not exist, an error response is generated (a usage- or resource-not-found error, respectively).

Options (via CLI/GET/POST.payload):

TODOs:

Create or Save Page

Status: implemented 20110922.

Required privileges: "k" (save) or "f" (create)

Request:

These work only in HTTP mode, not CLI mode. (FIXME: now that we can simulate POST from a file, these could be used in CLI mode.)

The semantic differences between save and create are:

Response payload example:

The same as for /json/wiki/get but the page content is not included in the response (only the metadata).

Request options (via GET or POST.payload object):

Wiki Diffs

Status: implemented 20120304

Required privileges: "h"

Request:

Response payload example:

{
  "v1":"e32ccdcda59e930c77c1e01cebace5d71253f621",
  "v2":"e15992f475760cdf3a9564d8f88cacb659ab4b07",
  "diff":"@@ -1,4 +1,9 @@...<SNIP>..."
}

Options:

This command does not verify that both UUIDs actually refer to the same page name, but do verify that they refer to wiki content.

Trivia: passing the same UUIDs to the /json/diff command will produce very different results - that one diffs the manifests of the commits.

TODOs:

Preview

Status: implemented 20120310

Required privileges: "k" (to limit its use to only those who can edit wiki pages). This limitation is up for debate/reconsideration.

Request:

This command wiki-processes arbitrary text sent from the client. To help curb potential abuse, its use is restricted to those with "k" access rights.

The POST.payload property must be a string containing Fossil wiki markup. The response payload is also a string, but contains the HTML-processed form of the string. Whether or not "all HTML" is allowed depends on site-level configuration options, and that changes how the input is processed.

Note that the links in the generated page are for the HTML interface, and will not work as-is for arbitrary JSON clients. In order to integrate the parsed content with JSON-based clients the HTML will probably need to be post-processed, e.g. using jQuery to fish out the links and re-map wiki page links to a JSON-capable page handler.

TODO: Update this to accept the other two wiki formats (which didn't exist when this API was implemented): markdown and plain text (which gets HTML-ized for preview purposes). That requires changing the payload to an object, perhaps simply submitting the same thing as /json/save. There's no reason we can't support both call forms.

Notes and TODOs

Potential TODOs: