Fossil SCM

fossil-scm / www / json-api / api-wiki.md
Source Blame History 277 lines
587d954… stephan 1 # JSON API: /wiki
587d954… stephan 2 ([⬑JSON API Index](index.md))
587d954… stephan 3
587d954… stephan 4 Jump to:
587d954… stephan 5
587d954… stephan 6 * [Page List](#list)
587d954… stephan 7 * [Fetch a Page](#get)
587d954… stephan 8 * [Create or Save Page](#create-save)
587d954… stephan 9 * [Wiki Diffs](#diffs)
587d954… stephan 10 * [Preview](#preview)
587d954… stephan 11 * [Notes and TODOs](#todo)
587d954… stephan 12
587d954… stephan 13 ---
587d954… stephan 14
587d954… stephan 15 <a id="list"></a>
587d954… stephan 16 # Page List
587d954… stephan 17
587d954… stephan 18 Returns a list of all pages, not including their content (which can be
587d954… stephan 19 arbitrarily large).
587d954… stephan 20
587d954… stephan 21 **Status:** implemented 201109xx
587d954… stephan 22
587d954… stephan 23 **Required privileges:** "j" or "o"
587d954… stephan 24
587d954… stephan 25 **Request:** `/json/wiki/list`
587d954… stephan 26
587d954… stephan 27 **Options:**
587d954… stephan 28
587d954… stephan 29 - `bool verbose` (=false) Changes the results to return much more
587d954… stephan 30 information. Added 20120219.
587d954… stephan 31 - `glob=wildcard` string (default=`*`). If set, only page names
587d954… stephan 32 matching the given wildcard are returned. Added 20120325.\
587d954… stephan 33 CLI: `--glob|-g STRING`
587d954… stephan 34 - `like=SQL LIKE string` (default=`%`). If set, only page names matching
587d954… stephan 35 the given SQL LIKE string are returned. Note that this match is
587d954… stephan 36 case-INsensitive. If both glob and like are given then only one will
587d954… stephan 37 work and which one takes precedence is unspecified. Added 20120325.\
587d954… stephan 38 CLI: `--like|-l STRING`
587d954… stephan 39 - `invert=bool` (default=false). If set to a true value, the glob/like
587d954… stephan 40 filter has a reverse meaning (pages *not* matching the wildcard are
587d954… stephan 41 returned). Added 20120329.\
587d954… stephan 42 CLI: `-i/--invert`
587d954… stephan 43
587d954… stephan 44 **Response payload: format depends on "verbose" option**
587d954… stephan 45
587d954… stephan 46 Non-verbose mode:
587d954… stephan 47
587d954… stephan 48 ```json
587d954… stephan 49 ["PageName1",..."PageNameN"]
587d954… stephan 50 ```
587d954… stephan 51
587d954… stephan 52 In verbose mode:
587d954… stephan 53
587d954… stephan 54 ```json
587d954… stephan 55 [{
587d954… stephan 56 "name":"Apache On Windows XP",
587d954… stephan 57 "uuid":"a7e68df71b95d35321b9d9aeec3c8068f991926c",
587d954… stephan 58 "user":"jeffrimko",
587d954… stephan 59 "timestamp":1310227825,
587d954… stephan 60 "size":793 /* in bytes */
587d954… stephan 61 },...]
587d954… stephan 62 ```
587d954… stephan 63
587d954… stephan 64 The verbose-mode output is the same as the [`/json/wiki/get`](#get) output, but
587d954… stephan 65 without the content. The size property of each reflects the *byte*
587d954… stephan 66 length of the raw (non-HTMLized) page content.
587d954… stephan 67
587d954… stephan 68 **Potential TODOs:**
587d954… stephan 69
587d954… stephan 70 - Allow specifying (in the request) a list/array of names, as opposed
587d954… stephan 71 to listing all pages. The page count is rarely very high, though, so
587d954… stephan 72 an "overload" is very unlikely. (i have one wiki with about 47 pages
587d954… stephan 73 in it.)
587d954… stephan 74
587d954… stephan 75 <a id="get"></a>
587d954… stephan 76 # Fetch a Page
587d954… stephan 77
587d954… stephan 78 Fetches a single wiki page, including content and significant metadata.
587d954… stephan 79
587d954… stephan 80 **Status:** implemented 20110922, but response format may change.
587d954… stephan 81
587d954… stephan 82 **Required privileges:** "j" or "o"
587d954… stephan 83
587d954… stephan 84 **Request:**
587d954… stephan 85
587d954… stephan 86 - GET: `/json/wiki/get?name=PageName`
587d954… stephan 87 - GET: `/json/wiki/get/PageName`
587d954… stephan 88 - POST: `/json/wiki/get` with page name as `POST.payload` or
587d954… stephan 89 `POST.payload.name`.
587d954… stephan 90
587d954… stephan 91 **Response payload example:**
587d954… stephan 92
587d954… stephan 93 ```json
587d954… stephan 94 {
587d954… stephan 95 "name": "Fossil",
587d954… stephan 96 "uuid": "...hex string...",
587d954… stephan 97 "parent": "uuid of parent (not set for first version of page)",
587d954… stephan 98 "user": "anonymous",
587d954… stephan 99 "timestamp": 1286143975,
587d954… stephan 100 "size": 1906, /* In bytes, not UTF8 characters!
587d954… stephan 101 Affected by format option! */
587d954… stephan 102 "content": "..."
587d954… stephan 103 }
587d954… stephan 104 ```
587d954… stephan 105
587d954… stephan 106 **FIXME:** it's missing the mimetype (that support was added to fossil
587d954… stephan 107 after this was implemented).
587d954… stephan 108
587d954… stephan 109 If given no page to load, or if asked to get a page which does not
587d954… stephan 110 exist, an error response is generated (a usage- or resource-not-found
587d954… stephan 111 error, respectively).
587d954… stephan 112
587d954… stephan 113 **Options (via CLI/GET/`POST.payload`):**
587d954… stephan 114
587d954… stephan 115 - `name=string`. The page to fetch. The latest version is fetched
587d954… stephan 116 unless the uuid paramter is supplied (in which case name is ignored). \
587d954… stephan 117 CLI: `--name|-n string`\
587d954… stephan 118 Optionally, the name may be the 4th positional argument/request path element.
587d954… stephan 119 - `uuid=string`. Fetches a specific version. The name parameter is
587d954… stephan 120 ignored when this is specified.\
587d954… stephan 121 CLI: `--uid|-u string`
587d954… stephan 122 - `format=string ("raw"|"html"|"none")` (default="raw"). Specifies the
587d954… stephan 123 format of the "content" payload value.\
587d954… stephan 124 CLI: `--format|-f string` \
587d954… stephan 125 The "none" format means to return no content. In that case the size
587d954… stephan 126 refers to the same size as the "raw" format.
587d954… stephan 127
587d954… stephan 128 **TODOs:**
587d954… stephan 129
587d954… stephan 130 - Support passing an array of names in the request (and change
587d954… stephan 131 response to return an array).
587d954… stephan 132
587d954… stephan 133 <a id="create-save"></a>
587d954… stephan 134 # Create or Save Page
587d954… stephan 135
587d954… stephan 136 **Status:** implemented 20110922.
587d954… stephan 137
587d954… stephan 138 **Required privileges:** "k" (save) or "f" (create)
587d954… stephan 139
587d954… stephan 140 **Request:**
587d954… stephan 141
587d954… stephan 142 - `/json/wiki/create`
587d954… stephan 143 - `/json/wiki/save`
587d954… stephan 144
587d954… stephan 145 These work only in HTTP mode, not CLI mode. (FIXME: now that we can
587d954… stephan 146 simulate POST from a file, these could be used in CLI mode.)
587d954… stephan 147
587d954… stephan 148 The semantic differences between save and create are:
587d954… stephan 149
587d954… stephan 150 - Save will fail if the page doesn't already exist whereas create will
587d954… stephan 151 fail if it does. The createIfNotExists option (described below) can
587d954… stephan 152 be used to create new pages using the save operation.
587d954… stephan 153 - The content property is optional for the create request, whereas it
587d954… stephan 154 is required to be a string for save requests (but it *may* be an
587d954… stephan 155 empty string). This requirement for save is *almost* arbitrary, and
587d954… stephan 156 is intended to prevent accidental erasing of existing page content
587d954… stephan 157 via API misuse.
587d954… stephan 158
587d954… stephan 159 **Response payload example:**
587d954… stephan 160
587d954… stephan 161 The same as for [`/json/wiki/get`](#get) but the page content is not
587d954… stephan 162 included in the response (only the metadata).
587d954… stephan 163
587d954… stephan 164 **Request options** (via GET or `POST.payload` object):
587d954… stephan 165
587d954… stephan 166 - `name=string` specifies the page name.
587d954… stephan 167 - `content=string` is the body text.\
587d954… stephan 168 Content is required for save (unless `createIfNotExists` is true *and*
587d954… stephan 169 the page does not exist), optional for create. It *may* be an empty
587d954… stephan 170 string.
7f5877e… stephan 171 - `mimetype=string` specifies the mimetype for the body, noting any any
7f5877e… stephan 172 unrecognized/unsupported mimetype is silently treated as
7f5877e… stephan 173 `text/x-fossil-wiki`.
587d954… stephan 174 - Save (not create) supports a `createIfNotExists` boolean option which
587d954… stephan 175 makes it a functional superset of the create/save features. i.e. it
587d954… stephan 176 will create if needed, else it will update. If createIfNotExists is
587d954… stephan 177 false (the default) then save will fail if given a page name which
587d954… stephan 178 does not refer to an existing page.
587d954… stephan 179 - **TODO:** add `commitMessage` string property. The fossil internals
587d954… stephan 180 don't have a way to do this at the moment (they can as of late 2019).
587d954… stephan 181 Since fossil wiki commits have always had the same default commit message, this is not a
587d954… stephan 182 high-priority addition. See:\
587d954… stephan 183 [](/doc/trunk/www/fileformat.wiki#wikichng)
587d954… stephan 184 - **Potential TODO:** we *could* optionally also support
587d954… stephan 185 multi-page saving using an array of pages in the request payload:\
587d954… stephan 186 `[… page objects … ]`
7f5877e… stephan 187
587d954… stephan 188
587d954… stephan 189
587d954… stephan 190 <a id="diffs"></a>
587d954… stephan 191 # Wiki Diffs
587d954… stephan 192
587d954… stephan 193 **Status:** implemented 20120304
587d954… stephan 194
587d954… stephan 195 **Required privileges:** "h"
587d954… stephan 196
587d954… stephan 197 **Request:**
587d954… stephan 198
587d954… stephan 199 - `/json/wiki/diff[/version1_UUID/version2_UUID]`
587d954… stephan 200
587d954… stephan 201 **Response payload example:**
587d954… stephan 202
587d954… stephan 203 ```json
587d954… stephan 204 {
587d954… stephan 205 "v1":"e32ccdcda59e930c77c1e01cebace5d71253f621",
587d954… stephan 206 "v2":"e15992f475760cdf3a9564d8f88cacb659ab4b07",
587d954… stephan 207 "diff":"@@ -1,4 +1,9 @@...<SNIP>..."
587d954… stephan 208 }
587d954… stephan 209 ```
587d954… stephan 210
587d954… stephan 211 **Options:**
587d954… stephan 212
587d954… stephan 213 - `v1=uuid` and `v2=uuid` specify the two versions to diff, and are
587d954… stephan 214 required parameters. They may optionally be specified as the two
587d954… stephan 215 URL/CLI parameters following the "diff" sub-command/path.
587d954… stephan 216
587d954… stephan 217 This command does not verify that both UUIDs actually refer to the same
587d954… stephan 218 page name, but do verify that they refer to wiki content.
587d954… stephan 219
587d954… stephan 220 Trivia: passing the same UUIDs to the `/json/diff` command will produce
587d954… stephan 221 very different results - that one diffs the manifests of the commits.
587d954… stephan 222
587d954… stephan 223 **TODOs:**
587d954… stephan 224
587d954… stephan 225 - Add options for changing the format of the diff, e.g. side-by-side
587d954… stephan 226 and enabling the HTML markup supported by the main fossil HTML GUI.
587d954… stephan 227 - Potentially do a name comparison to verify that the diff is against
587d954… stephan 228 the same page. That said, when "renaming" pages it might be useful
587d954… stephan 229 to diff two different pages.
587d954… stephan 230
587d954… stephan 231 <a id="preview"></a>
587d954… stephan 232 # Preview
587d954… stephan 233
587d954… stephan 234 **Status:** implemented 20120310
587d954… stephan 235
587d954… stephan 236 **Required privileges:** "k" (to limit its use to only those who can
587d954… stephan 237 edit wiki pages). This limitation is up for debate/reconsideration.
587d954… stephan 238
587d954… stephan 239 **Request:**
587d954… stephan 240
587d954… stephan 241 - `/json/wiki/preview`
587d954… stephan 242
587d954… stephan 243 This command wiki-processes arbitrary text sent from the client. To help
587d954… stephan 244 curb potential abuse, its use is restricted to those with "k" access
587d954… stephan 245 rights.
587d954… stephan 246
7f5877e… stephan 247 The `POST.payload` property must be either:
7f5877e… stephan 248
7f5877e… stephan 249 1) A string containing Fossil wiki markup.
7f5877e… stephan 250
7f5877e… stephan 251 2) An Object with a `body` property holding the text to render and a
7f5877e… stephan 252 `mimetype` property describing the wiki format:
7f5877e… stephan 253 `text/x-fossil-wiki` (the default), `text/x-markdown`, or
7f5877e… stephan 254 `text/plain`. Any unknown type is treated as `text/x-fossil-wiki`.
7f5877e… stephan 255
7f5877e… stephan 256 The response payload is a string containing the rendered page. Whether
7f5877e… stephan 257 or not "all HTML" is allowed depends on site-level configuration
7f5877e… stephan 258 options, and that changes how the input is processed.
587d954… stephan 259
587d954… stephan 260 Note that the links in the generated page are for the HTML interface,
587d954… stephan 261 and will not work as-is for arbitrary JSON clients. In order to
587d954… stephan 262 integrate the parsed content with JSON-based clients the HTML will
587d954… stephan 263 probably need to be post-processed, e.g. using jQuery to fish out the
587d954… stephan 264 links and re-map wiki page links to a JSON-capable page handler.
587d954… stephan 265
587d954… stephan 266
587d954… stephan 267 <a id="todo"></a>
587d954… stephan 268 # Notes and TODOs
587d954… stephan 269
587d954… stephan 270 - When server-parsing the wiki content, the generated
587d954… stephan 271 intra-wiki/intra-site links will only be useful in the context of
587d954… stephan 272 the original fossil UI (or a work-alike), not arbitrary JSON
587d954… stephan 273 client apps.
587d954… stephan 274
587d954… stephan 275 Potential TODOs:
587d954… stephan 276
587d954… stephan 277 - `/wiki/history` analog to the [](/whistory) page.

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button