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:

bool verbose (=false) Changes the results to return much more information. Added 20120219.
glob=wildcard string (default=*). If set, only page names matching the given wildcard are returned. Added 20120325.
CLI: --glob|-g STRING
like=SQL LIKE string (default=%). If set, only page names matching the given SQL LIKE string are returned. Note that this match is case-INsensitive. If both glob and like are given then only one will work and which one takes precedence is unspecified. Added 20120325.
CLI: --like|-l STRING
invert=bool (default=false). If set to a true value, the glob/like filter has a reverse meaning (pages not matching the wildcard are returned). Added 20120329.
CLI: -i/--invert

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:

Allow specifying (in the request) a list/array of names, as opposed to listing all pages. The page count is rarely very high, though, so an "overload" is very unlikely. (i have one wiki with about 47 pages in it.)

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:

GET: /json/wiki/get?name=PageName
GET: /json/wiki/get/PageName
POST: /json/wiki/get with page name as POST.payload or POST.payload.name.

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

name=string. The page to fetch. The latest version is fetched unless the uuid paramter is supplied (in which case name is ignored).
CLI: --name|-n string
Optionally, the name may be the 4th positional argument/request path element.
uuid=string. Fetches a specific version. The name parameter is ignored when this is specified.
CLI: --uid|-u string
format=string ("raw"|"html"|"none") (default="raw"). Specifies the format of the "content" payload value.
CLI: --format|-f string
The "none" format means to return no content. In that case the size refers to the same size as the "raw" format.

TODOs:

Support passing an array of names in the request (and change response to return an array).

Create or Save Page

Status: implemented 20110922.

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

Request:

/json/wiki/create
/json/wiki/save

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:

Save will fail if the page doesn't already exist whereas create will fail if it does. The createIfNotExists option (described below) can be used to create new pages using the save operation.
The content property is optional for the create request, whereas it is required to be a string for save requests (but it may be an empty string). This requirement for save is almost arbitrary, and is intended to prevent accidental erasing of existing page content via API misuse.

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

name=string specifies the page name.
content=string is the body text.
Content is required for save (unless createIfNotExists is true and the page does not exist), optional for create. It may be an empty string.
Save (not create) supports a createIfNotExists boolean option which makes it a functional superset of the create/save features. i.e. it will create if needed, else it will update. If createIfNotExists is false (the default) then save will fail if given a page name which does not refer to an existing page.
TODO: add commitMessage string property. The fossil internals don't have a way to do this at the moment (they can as of late 2019). Since fossil wiki commits have always had the same default commit message, this is not a high-priority addition. See:
/doc/trunk/www/fileformat.wiki#wikichng
Potential TODO: we could optionally also support multi-page saving using an array of pages in the request payload:
[… page objects … ]

Wiki Diffs

Status: implemented 20120304

Required privileges: "h"

Request:

/json/wiki/diff[/version1_UUID/version2_UUID]

Response payload example:

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

Options:

v1=uuid and v2=uuid specify the two versions to diff, and are required parameters. They may optionally be specified as the two URL/CLI parameters following the "diff" sub-command/path.

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:

Add options for changing the format of the diff, e.g. side-by-side and enabling the HTML markup supported by the main fossil HTML GUI.
Potentially do a name comparison to verify that the diff is against the same page. That said, when "renaming" pages it might be useful to diff two different pages.

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:

/json/wiki/preview

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

When server-parsing the wiki content, the generated intra-wiki/intra-site links will only be useful in the context of the original fossil UI (or a work-alike), not arbitrary JSON client apps.

Potential TODOs:

/wiki/history analog to the /whistory page.