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