Fossil SCM

Ported in /json/wiki and /json/artifact docs.

stephan 2020-01-28 10:20 trunk

Commit 587d954fb56fbde68fc34214839bd5916377bf30163d2be4328fb20a41f0dfce

Parent c95f11b4548d769…

5 files changed +159 +30 +301 +6 -6 +3 -18

+ www/json-api/api-artifact.md + www/json-api/api-index.md + www/json-api/api-wiki.md ~ www/json-api/conventions.md ~ www/json-api/index.md

A www/json-api/api-artifact.md

+159

		--- a/www/json-api/api-artifact.md
		+++ b/www/json-api/api-artifact.md
		@@ -0,0 +1,159 @@
	1	+# JSON API: /artifact
	2	+(i# JSON API: /artifact
	3	+([⬑JSON API Index](index.md))
	4	+
	5	+Jump to:
	6	+
	7	+* [Checkin Artifacts (Commits)](#checkin)
	8	+* [File Artifacts](#file)
	9	+* [Wiki Artifacts](#wiki)
	10	+
	11	+---
	12	+
	13	+<a id="checkin"></a>
	14	+# Checkin Artifacts (Commits)
	15	+
	16	+Returns information about checkin artifacts (commits).
	17	+
	18	+Status: implemented 201110xx
	19	+
	20	+Request:UUIDson/artifact/COMMIT_HASH`
	21	+
	22	+Required permissions: "o" (was "h" prior to 20120408)
	23	+
	24	+Response payload example: (CHANGED SIGNIFICANTLY ON 20120713)
	25	+
	26	+```json
	27	+{
	28	+"type":"checkin",
	29	+"name":"18dd383e5e7684e", // as given on CLI
	30	+"uuid":"18dd383e5e7684ecee327d3de7d3ff846069d1b2",
	31	+"isLeaf":false,
	32	+"user":"drh",
	33	+"comment":"Merge wideAnnotateUser and jsonWarnings into trunk.",
	34	+"timestamp":1330090810,
	35	+"parents":[
	36	+ // 1st UUIDy is primary parent hash:
	37	+ "3a44f95f40a193739aaafc2409f155df43e74a6f",
	38	+ // Remaining entriUUID,
	39	+ // Remaining entries are merged-in branch hashes:
	40	+ "86f6e675eb3f8761d70d8b82b052ce2b297fffd2",\
	41	+ "dbf4ecf414881c9aad6f4f125dab976258uuids, NOT commit UUIDin Artifacts (Commits)](#checkin)
	42	+* [File Artifacts](#file)
	43	+* [Wiki Artifacts](#wiki)
	44	+
	45	+---
	46	+
	47	+<a id="checkin"></a>
	48	+# Checkin Artifacts (Commits)
	49	+
	50	+Returns information about checkin artifacts (commits).
	51	+
	52	+Status: implemented 201110xx
	53	+
	54	+Request: `/json/artifact/COMMIT_HASH`
	55	+
	56	+ReUUIDd permissions: "o" (was "h" prior to 20120408)
	57	+
	58	+**Response payload example:UUIDUUIDUUID7fffd2",\
	59	+ "dbf4ecf414881c9aad6f4f125dab9762589ef3d7"\
	60	+],
	61	+"tags":["trunk"],
	62	+"files":[{
	63	+ "name":"src/diff.c",
	64	+ // BLOB hashes, NOT commit hashes:
	65	+ "uuuuids, not commiath":"/raw/src/diff.c?name=78c74c3b37e266f8f7e570d5cf476854b7af9d76"
	66	+ },
	67	+ ...]
	68	+}
	69	+```
	70	+
	71	+The "parents" property lists the parent hashes of the checkin. The
	72	+"parent" property of file entries refers to the parent hash of that
	73	+file. In the case of a merge there may be essentially an arbitrary
	74	+number. The first entry in the list is the "primary" parent. The primary
	75	+parent is the parent whicUUIDng entries are merged-in branch hashes:
	76	+ "86f6e675eb3f8761d70d8b82b052ce2b297fffd2",\
	77	+ "dbf4ecf414881c9aad6f4f125dab9762589ef3d7"\
	78	+],
	79	+"tags":["tru⬑JSON API Index](index.md))
	80	+
	81	+Jump to:
	82	+
	83	+* [Checkin Artifacts (Commits)](#checkin)
	84	+* [File Artifacts](#file)
	85	+* [Wiki Artifacts](#wiki)
	86	+
	87	+---
	88	+
	89	+<a id="checkin"></a>
	90	+# Checkin Artifacts (Commits)
	91	+
	92	+Returns information about checkin artifacts (commits).
	93	+
	94	+Status: implemented 201110xx
	95	+
	96	+Request: `/json/artifact/COMMIT_HASH`
	97	+
	98	+Required permissions: "o" (was "h" prior to 20120408)
	99	+
	100	+Response payload example: (CHANGED SIGNIFICANTLY ON 20120713)
	101	+
	102	+```json
	103	+{
	104	+"type":"checkin",
	105	+"name":"18dd383e5e7684e", // as given on CLI
	106	+"uuid":"18dd383e5e7684ecee327d3de7d3ff846069d1b2",
	107	+"isLeaf":false,
	108	+"user":"drh",
	109	+"comment":"Merge wideAnnotateUser and jsonWarnings into trunk.",
	110	+"timestamp":1330090810,
	111	+"parents":UUIDent hash:
	112	+ "3a44f95f40a193739aaafc2409f155df43e74a6f",
	113	+ // Remaining entrieuuide merged-in branch hashes:
	114	+ "86f6e675eb3f8761d70d8b82b052ce2b297fffd2",\
	115	+ "dbf4ecf414881c9aad6f4f125dab9762589ef3d7"\
	116	+],
	117	+"tags":["trunk"],
	118	+"files":[{
	119	+ "name":"src/diff.c",
	120	+ // BLOB hashes, NOT commit hashes:
	121	+ "uuid":"78c74c3b37e266f8f7e570d5cf476854b7af9d76",
	122	+ "parent":"b1fa7e636cf4e7b6ed20bba2d2680397f80c096a",
	123	+ "state":"modified",
	124	+ "downloadPath":"/raw/src/diff.c?name=78c74c3b37e266f8f7e570d5cf476854b7af9d76"
	125	+ },
	126	+ ...]
	127	+}
	128	+```
	129	+
	130	+The "parents" property lists the parent hashes of the checkin. The
	131	+"parent" property of file entries refers to the parent hash of that
	132	+file. In the case of a merge there may be essentially an arbitrary
	133	+number. The first entry in the list is the "primary" puuid As of
	134	+ 20120713 this option is only inspected if "format" is not specified.
	135	+
	136	+Response payload example: (CHANGED SIGNIFICANTLY ON 20120713)
	137	+
	138	+```json
	139	+{
	140	+"type":"file",
	141	+"name":"same name specified as FILE_HASH argument",
	142	+"size": 12345, // in bytes, independent of format=...
	143	+"parentUUIDson/artifact/COMMIT_HASH`
	144	+
	145	+**Rset for first generation.",
	146	+"checkins":[{
	147	+ "name":"src/json_detail.h",
	148	+ "timestamp":1319058803,
	149	+ "comment":"...",
	150	+ "user":"stephan",
	151	+ "checkin":"d2c1ae23a90b24f6ca1d7637193a59d5ecf3e680",
	152	+ "branch":"json",
	153	+ "state":"added\|modified\|removed"
	154	+ },
	155	+ ...],
	156	+/* The following "content" properties are only set if format=raw\|html */
	157	+"content": "file contents",
	158	+"contentSize": "size of content field, in bytes. Affected by the format option!",
	159	+"content

	--- a/www/json-api/api-artifact.md
	+++ b/www/json-api/api-artifact.md
	@@ -0,0 +1,159 @@

	--- a/www/json-api/api-artifact.md
	+++ b/www/json-api/api-artifact.md
	@@ -0,0 +1,159 @@
1	# JSON API: /artifact
2	(i# JSON API: /artifact
3	([⬑JSON API Index](index.md))
4
5	Jump to:
6
7	* [Checkin Artifacts (Commits)](#checkin)
8	* [File Artifacts](#file)
9	* [Wiki Artifacts](#wiki)
10
11	---
12
13	<a id="checkin"></a>
14	# Checkin Artifacts (Commits)
15
16	Returns information about checkin artifacts (commits).
17
18	Status: implemented 201110xx
19
20	Request:UUIDson/artifact/COMMIT_HASH`
21
22	Required permissions: "o" (was "h" prior to 20120408)
23
24	Response payload example: (CHANGED SIGNIFICANTLY ON 20120713)
25
26	```json
27	{
28	"type":"checkin",
29	"name":"18dd383e5e7684e", // as given on CLI
30	"uuid":"18dd383e5e7684ecee327d3de7d3ff846069d1b2",
31	"isLeaf":false,
32	"user":"drh",
33	"comment":"Merge wideAnnotateUser and jsonWarnings into trunk.",
34	"timestamp":1330090810,
35	"parents":[
36	// 1st UUIDy is primary parent hash:
37	"3a44f95f40a193739aaafc2409f155df43e74a6f",
38	// Remaining entriUUID,
39	// Remaining entries are merged-in branch hashes:
40	"86f6e675eb3f8761d70d8b82b052ce2b297fffd2",\
41	"dbf4ecf414881c9aad6f4f125dab976258uuids, NOT commit UUIDin Artifacts (Commits)](#checkin)
42	* [File Artifacts](#file)
43	* [Wiki Artifacts](#wiki)
44
45	---
46
47	<a id="checkin"></a>
48	# Checkin Artifacts (Commits)
49
50	Returns information about checkin artifacts (commits).
51
52	Status: implemented 201110xx
53
54	Request: `/json/artifact/COMMIT_HASH`
55
56	ReUUIDd permissions: "o" (was "h" prior to 20120408)
57
58	**Response payload example:UUIDUUIDUUID7fffd2",\
59	"dbf4ecf414881c9aad6f4f125dab9762589ef3d7"\
60	],
61	"tags":["trunk"],
62	"files":[{
63	"name":"src/diff.c",
64	// BLOB hashes, NOT commit hashes:
65	"uuuuids, not commiath":"/raw/src/diff.c?name=78c74c3b37e266f8f7e570d5cf476854b7af9d76"
66	},
67	...]
68	}
69	```
70
71	The "parents" property lists the parent hashes of the checkin. The
72	"parent" property of file entries refers to the parent hash of that
73	file. In the case of a merge there may be essentially an arbitrary
74	number. The first entry in the list is the "primary" parent. The primary
75	parent is the parent whicUUIDng entries are merged-in branch hashes:
76	"86f6e675eb3f8761d70d8b82b052ce2b297fffd2",\
77	"dbf4ecf414881c9aad6f4f125dab9762589ef3d7"\
78	],
79	"tags":["tru⬑JSON API Index](index.md))
80
81	Jump to:
82
83	* [Checkin Artifacts (Commits)](#checkin)
84	* [File Artifacts](#file)
85	* [Wiki Artifacts](#wiki)
86
87	---
88
89	<a id="checkin"></a>
90	# Checkin Artifacts (Commits)
91
92	Returns information about checkin artifacts (commits).
93
94	Status: implemented 201110xx
95
96	Request: `/json/artifact/COMMIT_HASH`
97
98	Required permissions: "o" (was "h" prior to 20120408)
99
100	Response payload example: (CHANGED SIGNIFICANTLY ON 20120713)
101
102	```json
103	{
104	"type":"checkin",
105	"name":"18dd383e5e7684e", // as given on CLI
106	"uuid":"18dd383e5e7684ecee327d3de7d3ff846069d1b2",
107	"isLeaf":false,
108	"user":"drh",
109	"comment":"Merge wideAnnotateUser and jsonWarnings into trunk.",
110	"timestamp":1330090810,
111	"parents":UUIDent hash:
112	"3a44f95f40a193739aaafc2409f155df43e74a6f",
113	// Remaining entrieuuide merged-in branch hashes:
114	"86f6e675eb3f8761d70d8b82b052ce2b297fffd2",\
115	"dbf4ecf414881c9aad6f4f125dab9762589ef3d7"\
116	],
117	"tags":["trunk"],
118	"files":[{
119	"name":"src/diff.c",
120	// BLOB hashes, NOT commit hashes:
121	"uuid":"78c74c3b37e266f8f7e570d5cf476854b7af9d76",
122	"parent":"b1fa7e636cf4e7b6ed20bba2d2680397f80c096a",
123	"state":"modified",
124	"downloadPath":"/raw/src/diff.c?name=78c74c3b37e266f8f7e570d5cf476854b7af9d76"
125	},
126	...]
127	}
128	```
129
130	The "parents" property lists the parent hashes of the checkin. The
131	"parent" property of file entries refers to the parent hash of that
132	file. In the case of a merge there may be essentially an arbitrary
133	number. The first entry in the list is the "primary" puuid As of
134	20120713 this option is only inspected if "format" is not specified.
135
136	Response payload example: (CHANGED SIGNIFICANTLY ON 20120713)
137
138	```json
139	{
140	"type":"file",
141	"name":"same name specified as FILE_HASH argument",
142	"size": 12345, // in bytes, independent of format=...
143	"parentUUIDson/artifact/COMMIT_HASH`
144
145	**Rset for first generation.",
146	"checkins":[{
147	"name":"src/json_detail.h",
148	"timestamp":1319058803,
149	"comment":"...",
150	"user":"stephan",
151	"checkin":"d2c1ae23a90b24f6ca1d7637193a59d5ecf3e680",
152	"branch":"json",
153	"state":"added\|modified\|removed"
154	},
155	...],
156	/* The following "content" properties are only set if format=raw\|html */
157	"content": "file contents",
158	"contentSize": "size of content field, in bytes. Affected by the format option!",
159	"content

A www/json-api/api-index.md

+30

		--- a/www/json-api/api-index.md
		+++ b/www/json-api/api-index.md
		@@ -0,0 +1,30 @@
	1	+# JSON API: API Index
	2	+([⬑JSON API Index](index.md))
	3	+
	4	+The available APIs are listed below, sorted alphabetically by general topic.
	5	+
	6	+NOTE that request/response examples shown in the individual API
	7	+pages do not show [the standard request/response envelope](conventions.md)
	8	+(for brevity and sanity).
	9	+
	10	+Achtung: just because a given feature is described as being
	11	+implemented does not mean that the implementation is "final" - it may be
	12	+changed at any time until we find/implement useful APIs.
	13	+
	14	+The APIs, alphabetically by category:
	15	+
	16	+* [Artifact Info](api-artifact.md)
	17	+* TODO [Authentication](api-auth.md)
	18	+* TODO [Branches](api-branches.md)
	19	+* TODO[Branches](api-branch.md)
	20	+* [Config](api-config.md)
	21	+* TODO [ [Directory Listing](api-dir.md)
	22	+* [File Info](api-finfo.md)
	23	+* [Repository Stats](api-stat.md)
	24	+* [SQL Query](api-query.md)
	25	+* [Tags](api-tag.md)
	26	+* TODO [Tickets](api-tickets.md)
	27	+* TODO [Timeline](api-timeline.md)
	28	+* TODO [User Management](api-users.md)
	29	+* TODO [Version](api-version.md)
	30	+* [Wik

	--- a/www/json-api/api-index.md
	+++ b/www/json-api/api-index.md
	@@ -0,0 +1,30 @@

	--- a/www/json-api/api-index.md
	+++ b/www/json-api/api-index.md
	@@ -0,0 +1,30 @@
1	# JSON API: API Index
2	([⬑JSON API Index](index.md))
3
4	The available APIs are listed below, sorted alphabetically by general topic.
5
6	NOTE that request/response examples shown in the individual API
7	pages do not show [the standard request/response envelope](conventions.md)
8	(for brevity and sanity).
9
10	Achtung: just because a given feature is described as being
11	implemented does not mean that the implementation is "final" - it may be
12	changed at any time until we find/implement useful APIs.
13
14	The APIs, alphabetically by category:
15
16	* [Artifact Info](api-artifact.md)
17	* TODO [Authentication](api-auth.md)
18	* TODO [Branches](api-branches.md)
19	* TODO[Branches](api-branch.md)
20	* [Config](api-config.md)
21	* TODO [ [Directory Listing](api-dir.md)
22	* [File Info](api-finfo.md)
23	* [Repository Stats](api-stat.md)
24	* [SQL Query](api-query.md)
25	* [Tags](api-tag.md)
26	* TODO [Tickets](api-tickets.md)
27	* TODO [Timeline](api-timeline.md)
28	* TODO [User Management](api-users.md)
29	* TODO [Version](api-version.md)
30	* [Wik

A www/json-api/api-wiki.md

+301

		--- a/www/json-api/api-wiki.md
		+++ b/www/json-api/api-wiki.md
		@@ -0,0 +1,301 @@
	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 bSave (not create) supports a `createIfNotExists` boolean option which
	170	+ makes it a functional superset of the create/save features. i.e. it
	171	+ will create if needed, else it will update. If createIfNotExists is
	172	+ false (the default) then save will fail if given a page name which
	173	+ does not refer to an existing page.
	174	+- TODO: add `commitMessage` string property. The fossil internals
	175	+ don't have a way to do this at the moment (they can as of late 2019).
	176	+ Since fossil wiki commits have always had the same default commit message, this is not a
	177	+ high-priority addition. See:\
	178	+ [](/doc/trunk/www/fileformat.wiki#wikichng)
	179	+- Potential TODO: we could optionally also support
	180	+ multi-page saving using an array of pages in the request payload:\
	181	+ `… page objects … ]`
	182	+
	183	+
	184	+
	185	+<a id="diffs"></a>
	186	+# Wiki Diffs
	187	+
	188	+Status: implemented 20120304
	189	+
	190	+Required privileges: "h"
	191	+
	192	+Request:
	193	+
	194	+- `/json/wiki/diff[/version1_UUID/version2_UUID]`
	195	+
	196	+Response payload example:
	197	+
	198	+```json
	199	+{
	200	+ "v1":"e32ccdcda59e930c77c1e01cebace5d71253f621",
	201	+ "v2":"e15992f475760cdf3a9564d8f88cacb659ab4b07",
	202	+ "diff":"@@ -1,4 +1,9 @@...<SNIP>..."
	203	+}
	204	+```
	205	+
	206	+Options:
	207	+
	208	+- `v1=uuid` and `v2=uuid` specify the two versions to diff, and are
	209	+ required parameters. They may optionally be specified as the two
	210	+ URL/CLI parameters following the "diff" sub-command/path.
	211	+
	212	+This command does not verify that both UUIDs actually refer to the same
	213	+page name, but do verify that they refer to wiki content.
	214	+
	215	+Trivia: passing the same UUIDs to the `/json/diff` command will produce
	216	+very different results - that one diffs the manifests of the commits.
	217	+
	218	+TODOs:
	219	+
	220	+- Add options for changing the format of the diff, e.g. side-by-side
	221	+ and enabling the HTML markup supported by the main fossil HTML GUI.
	222	+- Potentially do a name comparison to verify that the diff is against
	223	+ the same page. That said, when "renaming" pages it might be useful
	224	+ to diff two different pages.
	225	+
	226	+<a id="preview"></a>
	227	+# Preview
	228	+
	229	+Status: implemented 20120310
	230	+
	231	+Required privileges: "k" (to limit its use to only those who can
	232	+edit wiki pages). This limitation is up for debate/reconsideration.
	233	+
	234	+Request:
	235	+
	236	+- `/json/wiki/preview`
	237	+
	238	+This command wiki-processes arbitrary text sent from the client. To help
	239	+curb potential abuse, its use is restricted to those with "k" access
	240	+rights.
	241	+
	242	+The `POSTart
	243	+ multi-page saving using
	244	+markup. UUID]`
	245	+
	246	+**Response payloalso a string, but contains the
	247	+HTML-processed form of the string. Whether 0c77c1e01cebace5d71253f621",
	248	+564d8f88cacb659ab4b07",
	249	+ "diff":"@ acb659ab4b07",
	250	+ "diff":"@@ -1,4
	251	+ JSON API: /wiki
	252	+([⬑JSON API Index](index.md))
	253	+
	254	+Jump to:
	255	+
	256	+* [Page List](#list)
	257	+* [Fetch a Page](#get)
	258	+* [Create or Save Page](#create-save)
	259	+* [Wiki Diffs](#diffs)
	260	+* [Preview](#preview)
	261	+* [Notes and TODOs](#todo)
	262	+
	263	+---
	264	+
	265	+<a id="list"></a>
	266	+# Page List
	267	+
	268	+Returns a list of all pages, not including their content (which can be
	269	+arbib11;JSON API Index](index.md))
	270	+
	271	+Jump to:
	272	+
	273	+* [Page List](#list)
	274	+* [Fetch a Page](#get)
	275	+* [Create or Save Page](#create-save)
	276	+* [Wiki Diffs](#diffs)
	277	+* [Preview](#preview)
	278	+* [Notes and TODOs](#todo)
	279	+
	280	+---
	281	+
	282	+<a id="list"></a>
	283	+# Page List
	284	+
	285	+Returns a list of all pages, not including their content (which can be
	286	+arbitrarily large).
	287	+
	288	+Status: a JSON-capable page handler.
	289	+
	290	+
	291	+<a id="todo"></a>
	292	+# Notes and TODOs
	293	+
	294	+- When server-parsing the wiki content, the generated
	295	+ intra-wiki/intra-site links will only be useful in the context of
	296	+ the original fossil UI (or a work-alike), not arbitrary JSON
	297	+ client apps.
	298	+
	299	+Potential TODOs:
	300	+
	301	+- `/wiki/history` analog to the [](/whistory) page.

	--- a/www/json-api/api-wiki.md
	+++ b/www/json-api/api-wiki.md
	@@ -0,0 +1,301 @@

	--- a/www/json-api/api-wiki.md
	+++ b/www/json-api/api-wiki.md
	@@ -0,0 +1,301 @@
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 bSave (not create) supports a `createIfNotExists` boolean option which
170	makes it a functional superset of the create/save features. i.e. it
171	will create if needed, else it will update. If createIfNotExists is
172	false (the default) then save will fail if given a page name which
173	does not refer to an existing page.
174	- TODO: add `commitMessage` string property. The fossil internals
175	don't have a way to do this at the moment (they can as of late 2019).
176	Since fossil wiki commits have always had the same default commit message, this is not a
177	high-priority addition. See:\
178	[](/doc/trunk/www/fileformat.wiki#wikichng)
179	- Potential TODO: we could optionally also support
180	multi-page saving using an array of pages in the request payload:\
181	`… page objects … ]`
182
183
184
185	<a id="diffs"></a>
186	# Wiki Diffs
187
188	Status: implemented 20120304
189
190	Required privileges: "h"
191
192	Request:
193
194	- `/json/wiki/diff[/version1_UUID/version2_UUID]`
195
196	Response payload example:
197
198	```json
199	{
200	"v1":"e32ccdcda59e930c77c1e01cebace5d71253f621",
201	"v2":"e15992f475760cdf3a9564d8f88cacb659ab4b07",
202	"diff":"@@ -1,4 +1,9 @@...<SNIP>..."
203	}
204	```
205
206	Options:
207
208	- `v1=uuid` and `v2=uuid` specify the two versions to diff, and are
209	required parameters. They may optionally be specified as the two
210	URL/CLI parameters following the "diff" sub-command/path.
211
212	This command does not verify that both UUIDs actually refer to the same
213	page name, but do verify that they refer to wiki content.
214
215	Trivia: passing the same UUIDs to the `/json/diff` command will produce
216	very different results - that one diffs the manifests of the commits.
217
218	TODOs:
219
220	- Add options for changing the format of the diff, e.g. side-by-side
221	and enabling the HTML markup supported by the main fossil HTML GUI.
222	- Potentially do a name comparison to verify that the diff is against
223	the same page. That said, when "renaming" pages it might be useful
224	to diff two different pages.
225
226	<a id="preview"></a>
227	# Preview
228
229	Status: implemented 20120310
230
231	Required privileges: "k" (to limit its use to only those who can
232	edit wiki pages). This limitation is up for debate/reconsideration.
233
234	Request:
235
236	- `/json/wiki/preview`
237
238	This command wiki-processes arbitrary text sent from the client. To help
239	curb potential abuse, its use is restricted to those with "k" access
240	rights.
241
242	The `POSTart
243	multi-page saving using
244	markup. UUID]`
245
246	**Response payloalso a string, but contains the
247	HTML-processed form of the string. Whether 0c77c1e01cebace5d71253f621",
248	564d8f88cacb659ab4b07",
249	"diff":"@ acb659ab4b07",
250	"diff":"@@ -1,4
251	JSON API: /wiki
252	([⬑JSON API Index](index.md))
253
254	Jump to:
255
256	* [Page List](#list)
257	* [Fetch a Page](#get)
258	* [Create or Save Page](#create-save)
259	* [Wiki Diffs](#diffs)
260	* [Preview](#preview)
261	* [Notes and TODOs](#todo)
262
263	---
264
265	<a id="list"></a>
266	# Page List
267
268	Returns a list of all pages, not including their content (which can be
269	arbib11;JSON API Index](index.md))
270
271	Jump to:
272
273	* [Page List](#list)
274	* [Fetch a Page](#get)
275	* [Create or Save Page](#create-save)
276	* [Wiki Diffs](#diffs)
277	* [Preview](#preview)
278	* [Notes and TODOs](#todo)
279
280	---
281
282	<a id="list"></a>
283	# Page List
284
285	Returns a list of all pages, not including their content (which can be
286	arbitrarily large).
287
288	Status: a JSON-capable page handler.
289
290
291	<a id="todo"></a>
292	# Notes and TODOs
293
294	- When server-parsing the wiki content, the generated
295	intra-wiki/intra-site links will only be useful in the context of
296	the original fossil UI (or a work-alike), not arbitrary JSON
297	client apps.
298
299	Potential TODOs:
300
301	- `/wiki/history` analog to the [](/whistory) page.

M www/json-api/conventions.md

+6 -6

		--- www/json-api/conventions.md
		+++ www/json-api/conventions.md
		@@ -49,16 +49,16 @@
49	49	committing new files entirely, require POST data. This is fundamentally
50	50	very simple to do - clients post plain/unencoded JSON using a common
51	51	wrapper envelope which contains the request-specific data to submit as
52	52	well as some request-independent information (like authentication data).
53	53
	54	+<a id="request-envelope"></a>
54	55	## POST Request Envelope
55	56
56	57	POST requests are sent to the same URL as their GET counterpart (if any,
57	58	else their own path), and are sent as plain-text/unencoded JSON wrapped
58	59	in a common request envelope with the following properties:
59		-
60	60
61	61	(TODO: convert to a simple list...)
62	62	```
63	63	+-----------------------------------+-----------------------------------+
64	64	\| requestId \| Optional arbitrary JSON value, \|
		@@ -144,15 +144,15 @@
144	144	POST requests without such an envelope will be rejected, generating a
145	145	Fossil/JSON error response (as opposed to an HTTP error response). GET
146	146	requests, by definition, never have an envelope.
147	147
148	148	POSTed client requests must send a Content-Type header of either
149		-application/json , application/javascript, or text/plain, or the
	149	+`application/json` , `application/javascript`, or `text/plain`, or the
150	150	JSON-handling code will never see the POST data. The POST handler
151		-optimistically assumes that type text/plain "might be JSON", since
152		-application/json is a newer convention which many existing clients do
153		-not use.
	151	+optimistically assumes that type `text/plain` "might be JSON", since
	152	+`application/json` is a newer convention which many existing clients
	153	+do not use (as of the time these docs were written, back in 2011).
154	154
155	155	## POST Envelope vs. `POST.payload`
156	156
157	157
158	158	When this document refers to POST data, it is referring to top-level
		@@ -393,11 +393,11 @@
393	393	UTF-8 encoding (which is what we use). That means if your console cannot
394	394	handle UTF-8 then using this API in CLI mode might (depending on the
395	395	content) render garbage on your screen.
396	396
397	397
398		-<a href="cli-vs-http"></a>
	398	+<a id="cli-vs-http"></a>
399	399	# CLI vs. HTTP Mode
400	400
401	401	CLI (command-line interface) and HTTP modes (CGI and standalone server)
402	402	are consolidated in the same implementations and behave essentially
403	403	identically, with only minor exceptions.
404	404

	--- www/json-api/conventions.md
	+++ www/json-api/conventions.md
	@@ -49,16 +49,16 @@
49	committing new files entirely, require POST data. This is fundamentally
50	very simple to do - clients post plain/unencoded JSON using a common
51	wrapper envelope which contains the request-specific data to submit as
52	well as some request-independent information (like authentication data).
53

54	## POST Request Envelope
55
56	POST requests are sent to the same URL as their GET counterpart (if any,
57	else their own path), and are sent as plain-text/unencoded JSON wrapped
58	in a common request envelope with the following properties:
59
60
61	(TODO: convert to a simple list...)
62	```
63	+-----------------------------------+-----------------------------------+
64	\| requestId \| Optional arbitrary JSON value, \|
	@@ -144,15 +144,15 @@
144	POST requests without such an envelope will be rejected, generating a
145	Fossil/JSON error response (as opposed to an HTTP error response). GET
146	requests, by definition, never have an envelope.
147
148	POSTed client requests must send a Content-Type header of either
149	application/json , application/javascript, or text/plain, or the
150	JSON-handling code will never see the POST data. The POST handler
151	optimistically assumes that type text/plain "might be JSON", since
152	application/json is a newer convention which many existing clients do
153	not use.
154
155	## POST Envelope vs. `POST.payload`
156
157
158	When this document refers to POST data, it is referring to top-level
	@@ -393,11 +393,11 @@
393	UTF-8 encoding (which is what we use). That means if your console cannot
394	handle UTF-8 then using this API in CLI mode might (depending on the
395	content) render garbage on your screen.
396
397
398	<a href="cli-vs-http"></a>
399	# CLI vs. HTTP Mode
400
401	CLI (command-line interface) and HTTP modes (CGI and standalone server)
402	are consolidated in the same implementations and behave essentially
403	identically, with only minor exceptions.
404

	--- www/json-api/conventions.md
	+++ www/json-api/conventions.md
	@@ -49,16 +49,16 @@
49	committing new files entirely, require POST data. This is fundamentally
50	very simple to do - clients post plain/unencoded JSON using a common
51	wrapper envelope which contains the request-specific data to submit as
52	well as some request-independent information (like authentication data).
53
54	<a id="request-envelope"></a>
55	## POST Request Envelope
56
57	POST requests are sent to the same URL as their GET counterpart (if any,
58	else their own path), and are sent as plain-text/unencoded JSON wrapped
59	in a common request envelope with the following properties:

60
61	(TODO: convert to a simple list...)
62	```
63	+-----------------------------------+-----------------------------------+
64	\| requestId \| Optional arbitrary JSON value, \|
	@@ -144,15 +144,15 @@
144	POST requests without such an envelope will be rejected, generating a
145	Fossil/JSON error response (as opposed to an HTTP error response). GET
146	requests, by definition, never have an envelope.
147
148	POSTed client requests must send a Content-Type header of either
149	`application/json` , `application/javascript`, or `text/plain`, or the
150	JSON-handling code will never see the POST data. The POST handler
151	optimistically assumes that type `text/plain` "might be JSON", since
152	`application/json` is a newer convention which many existing clients
153	do not use (as of the time these docs were written, back in 2011).
154
155	## POST Envelope vs. `POST.payload`
156
157
158	When this document refers to POST data, it is referring to top-level
	@@ -393,11 +393,11 @@
393	UTF-8 encoding (which is what we use). That means if your console cannot
394	handle UTF-8 then using this API in CLI mode might (depending on the
395	content) render garbage on your screen.
396
397
398	<a id="cli-vs-http"></a>
399	# CLI vs. HTTP Mode
400
401	CLI (command-line interface) and HTTP modes (CGI and standalone server)
402	are consolidated in the same implementations and behave essentially
403	identically, with only minor exceptions.
404

M www/json-api/index.md

+3 -18

		--- www/json-api/index.md
		+++ www/json-api/index.md
		@@ -1,6 +1,6 @@
1		-# Fossil JSON API Index
	1	+# JSON API Index
2	2
3	3	THIS IS A WORK IN PROGRESS, starting 2020-01-28, porting 50-odd
4	4	pages of documentation from GoogleDocs. Most of the index is
5	5	placeholders.
6	6
		@@ -8,23 +8,8 @@
8	8	API aims to provide access to most of the primary fossil features via
9	9	AJAX-style interfaces.
10	10
11	11	* [Introduction](intro.md)
12	12	* [General API Conventions](conventions.md)
13		-* TODO [Tips & Tricks](tips.md)
	13	+* [Tips & Tricks](tips.md)
14	14	* [Hacking Guide](hacking.md)
15		-* APIs (Alphabetically by category)
16		- * TODO [Artifact Info](api-artifact.md)
17		- * TODO [Authentication](api-auth.md)
18		- * TODO [Branches](api-branches.md)
19		- * TODO [Config](api-config.md)
20		- * TODO [Diffs](api-diffs.md)
21		- * TODO [Directory Listing](api-dir.md)
22		- * TODO [File Info](api-finfo.md)
23		- * TODO [SQL Query](api-query.md)
24		- * TODO [Stats](api-stats.md)
25		- * TODO [Tags](api-tags.md)
26		- * TODO [Tickets](api-tickets.md)
27		- * TODO [Timeline](api-timeline.md)
28		- * TODO [User Management](api-users.md)
29		- * TODO [Version](api-version.md)
30		- * TODO [Wiki](api-wiki.md)
	15	+* [APIs](api-index.md)
31	16

	--- www/json-api/index.md
	+++ www/json-api/index.md
	@@ -1,6 +1,6 @@
1	# Fossil JSON API Index
2
3	THIS IS A WORK IN PROGRESS, starting 2020-01-28, porting 50-odd
4	pages of documentation from GoogleDocs. Most of the index is
5	placeholders.
6
	@@ -8,23 +8,8 @@
8	API aims to provide access to most of the primary fossil features via
9	AJAX-style interfaces.
10
11	* [Introduction](intro.md)
12	* [General API Conventions](conventions.md)
13	* TODO [Tips & Tricks](tips.md)
14	* [Hacking Guide](hacking.md)
15	* APIs (Alphabetically by category)
16	* TODO [Artifact Info](api-artifact.md)
17	* TODO [Authentication](api-auth.md)
18	* TODO [Branches](api-branches.md)
19	* TODO [Config](api-config.md)
20	* TODO [Diffs](api-diffs.md)
21	* TODO [Directory Listing](api-dir.md)
22	* TODO [File Info](api-finfo.md)
23	* TODO [SQL Query](api-query.md)
24	* TODO [Stats](api-stats.md)
25	* TODO [Tags](api-tags.md)
26	* TODO [Tickets](api-tickets.md)
27	* TODO [Timeline](api-timeline.md)
28	* TODO [User Management](api-users.md)
29	* TODO [Version](api-version.md)
30	* TODO [Wiki](api-wiki.md)
31

	--- www/json-api/index.md
	+++ www/json-api/index.md
	@@ -1,6 +1,6 @@
1	# JSON API Index
2
3	THIS IS A WORK IN PROGRESS, starting 2020-01-28, porting 50-odd
4	pages of documentation from GoogleDocs. Most of the index is
5	placeholders.
6
	@@ -8,23 +8,8 @@
8	API aims to provide access to most of the primary fossil features via
9	AJAX-style interfaces.
10
11	* [Introduction](intro.md)
12	* [General API Conventions](conventions.md)
13	* [Tips & Tricks](tips.md)
14	* [Hacking Guide](hacking.md)
15	* [APIs](api-index.md)















16

Fossil SCM

Keyboard Shortcuts