Fossil SCM
Ported in the remaining JSON API docs. Combined the API index into the main index. Replaced the pandoc-exported tables with lists. A couple patches to the C bits for issues found during doc porting.
Commit
514dd66f3354dec0076c58332167d1b6431483723014339ea412013b1f9b2e3a
Parent
85967b7c46f0f09…
10 files changed
+10
-1
+2
-1
-31
+92
+136
+146
+142
+32
+214
-424
+30
-6
+10
-1
| --- src/json_artifact.c | ||
| +++ src/json_artifact.c | ||
| @@ -230,11 +230,12 @@ | ||
| 230 | 230 | ** Internal mapping of /json/artifact/FOO commands/callbacks. |
| 231 | 231 | */ |
| 232 | 232 | static ArtifactDispatchEntry ArtifactDispatchList[] = { |
| 233 | 233 | {"checkin", json_artifact_ci}, |
| 234 | 234 | {"file", json_artifact_file}, |
| 235 | -{"tag", NULL}, | |
| 235 | +/*{"tag", NULL}, //impl missing */ | |
| 236 | +/*{"technote", NULL}, //impl missing */ | |
| 236 | 237 | {"ticket", json_artifact_ticket}, |
| 237 | 238 | {"wiki", json_artifact_wiki}, |
| 238 | 239 | /* Final entry MUST have a NULL name. */ |
| 239 | 240 | {NULL,NULL} |
| 240 | 241 | }; |
| @@ -476,10 +477,18 @@ | ||
| 476 | 477 | continue; |
| 477 | 478 | }else{ |
| 478 | 479 | entry = (*dispatcher->func)(pay, rid); |
| 479 | 480 | break; |
| 480 | 481 | } |
| 482 | + } | |
| 483 | + if(entry==0){ | |
| 484 | + g.json.resultCode = FSL_JSON_E_RESOURCE_NOT_FOUND | |
| 485 | + /* This is not quite right. We need a new result code | |
| 486 | + for this case. */; | |
| 487 | + g.zErrMsg = mprintf("Missing implementation for " | |
| 488 | + "artifacts of this type."); | |
| 489 | + goto error; | |
| 481 | 490 | } |
| 482 | 491 | if(!g.json.resultCode){ |
| 483 | 492 | assert( NULL != entry ); |
| 484 | 493 | assert( NULL != zType ); |
| 485 | 494 | cson_object_set( pay, "type", json_new_string(zType) ); |
| 486 | 495 |
| --- src/json_artifact.c | |
| +++ src/json_artifact.c | |
| @@ -230,11 +230,12 @@ | |
| 230 | ** Internal mapping of /json/artifact/FOO commands/callbacks. |
| 231 | */ |
| 232 | static ArtifactDispatchEntry ArtifactDispatchList[] = { |
| 233 | {"checkin", json_artifact_ci}, |
| 234 | {"file", json_artifact_file}, |
| 235 | {"tag", NULL}, |
| 236 | {"ticket", json_artifact_ticket}, |
| 237 | {"wiki", json_artifact_wiki}, |
| 238 | /* Final entry MUST have a NULL name. */ |
| 239 | {NULL,NULL} |
| 240 | }; |
| @@ -476,10 +477,18 @@ | |
| 476 | continue; |
| 477 | }else{ |
| 478 | entry = (*dispatcher->func)(pay, rid); |
| 479 | break; |
| 480 | } |
| 481 | } |
| 482 | if(!g.json.resultCode){ |
| 483 | assert( NULL != entry ); |
| 484 | assert( NULL != zType ); |
| 485 | cson_object_set( pay, "type", json_new_string(zType) ); |
| 486 |
| --- src/json_artifact.c | |
| +++ src/json_artifact.c | |
| @@ -230,11 +230,12 @@ | |
| 230 | ** Internal mapping of /json/artifact/FOO commands/callbacks. |
| 231 | */ |
| 232 | static ArtifactDispatchEntry ArtifactDispatchList[] = { |
| 233 | {"checkin", json_artifact_ci}, |
| 234 | {"file", json_artifact_file}, |
| 235 | /*{"tag", NULL}, //impl missing */ |
| 236 | /*{"technote", NULL}, //impl missing */ |
| 237 | {"ticket", json_artifact_ticket}, |
| 238 | {"wiki", json_artifact_wiki}, |
| 239 | /* Final entry MUST have a NULL name. */ |
| 240 | {NULL,NULL} |
| 241 | }; |
| @@ -476,10 +477,18 @@ | |
| 477 | continue; |
| 478 | }else{ |
| 479 | entry = (*dispatcher->func)(pay, rid); |
| 480 | break; |
| 481 | } |
| 482 | } |
| 483 | if(entry==0){ |
| 484 | g.json.resultCode = FSL_JSON_E_RESOURCE_NOT_FOUND |
| 485 | /* This is not quite right. We need a new result code |
| 486 | for this case. */; |
| 487 | g.zErrMsg = mprintf("Missing implementation for " |
| 488 | "artifacts of this type."); |
| 489 | goto error; |
| 490 | } |
| 491 | if(!g.json.resultCode){ |
| 492 | assert( NULL != entry ); |
| 493 | assert( NULL != zType ); |
| 494 | cson_object_set( pay, "type", json_new_string(zType) ); |
| 495 |
+2
-1
| --- src/json_timeline.c | ||
| +++ src/json_timeline.c | ||
| @@ -35,11 +35,12 @@ | ||
| 35 | 35 | that we end up with HTTP clients using 3 different names |
| 36 | 36 | for the same requests. |
| 37 | 37 | */ |
| 38 | 38 | {"branch", json_timeline_branch, 0}, |
| 39 | 39 | {"checkin", json_timeline_ci, 0}, |
| 40 | -{"event", json_timeline_event, 0}, | |
| 40 | +{"event" /* old name for technotes */, json_timeline_event, 0}, | |
| 41 | +{"technote", json_timeline_event, 0}, | |
| 41 | 42 | {"ticket", json_timeline_ticket, 0}, |
| 42 | 43 | {"wiki", json_timeline_wiki, 0}, |
| 43 | 44 | /* Last entry MUST have a NULL name. */ |
| 44 | 45 | {NULL,NULL,0} |
| 45 | 46 | }; |
| 46 | 47 | |
| 47 | 48 | DELETED www/json-api/api-index.md |
| 48 | 49 | ADDED www/json-api/api-misc.md |
| 49 | 50 | ADDED www/json-api/api-ticket.md |
| 50 | 51 | ADDED www/json-api/api-timeline.md |
| 51 | 52 | ADDED www/json-api/api-user.md |
| 52 | 53 | ADDED www/json-api/api-version.md |
| --- src/json_timeline.c | |
| +++ src/json_timeline.c | |
| @@ -35,11 +35,12 @@ | |
| 35 | that we end up with HTTP clients using 3 different names |
| 36 | for the same requests. |
| 37 | */ |
| 38 | {"branch", json_timeline_branch, 0}, |
| 39 | {"checkin", json_timeline_ci, 0}, |
| 40 | {"event", json_timeline_event, 0}, |
| 41 | {"ticket", json_timeline_ticket, 0}, |
| 42 | {"wiki", json_timeline_wiki, 0}, |
| 43 | /* Last entry MUST have a NULL name. */ |
| 44 | {NULL,NULL,0} |
| 45 | }; |
| 46 | |
| 47 | ELETED www/json-api/api-index.md |
| 48 | DDED www/json-api/api-misc.md |
| 49 | DDED www/json-api/api-ticket.md |
| 50 | DDED www/json-api/api-timeline.md |
| 51 | DDED www/json-api/api-user.md |
| 52 | DDED www/json-api/api-version.md |
| --- src/json_timeline.c | |
| +++ src/json_timeline.c | |
| @@ -35,11 +35,12 @@ | |
| 35 | that we end up with HTTP clients using 3 different names |
| 36 | for the same requests. |
| 37 | */ |
| 38 | {"branch", json_timeline_branch, 0}, |
| 39 | {"checkin", json_timeline_ci, 0}, |
| 40 | {"event" /* old name for technotes */, json_timeline_event, 0}, |
| 41 | {"technote", json_timeline_event, 0}, |
| 42 | {"ticket", json_timeline_ticket, 0}, |
| 43 | {"wiki", json_timeline_wiki, 0}, |
| 44 | /* Last entry MUST have a NULL name. */ |
| 45 | {NULL,NULL,0} |
| 46 | }; |
| 47 | |
| 48 | ELETED www/json-api/api-index.md |
| 49 | DDED www/json-api/api-misc.md |
| 50 | DDED www/json-api/api-ticket.md |
| 51 | DDED www/json-api/api-timeline.md |
| 52 | DDED www/json-api/api-user.md |
| 53 | DDED www/json-api/api-version.md |
D
www/json-api/api-index.md
-31
| --- a/www/json-api/api-index.md | ||
| +++ b/www/json-api/api-index.md | ||
| @@ -1,31 +0,0 @@ | ||
| 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 | -* [Authentication](api-auth.md) | |
| 18 | -* [Branches](api-branch.md) | |
| 19 | -* [Checkout Status](api-checkout.md) | |
| 20 | -* [Config](api-config.md) | |
| 21 | -* [Diffs](api-diff.md) | |
| 22 | -* [Directory Listing](api-dir.md) | |
| 23 | -* [File Info](api-finfo.md) | |
| 24 | -* [Repository Stats](api-stat.md) | |
| 25 | -* [SQL Query](api-query.md) | |
| 26 | -* [Tags](api-tag.md) | |
| 27 | -* TODO [Tickets](api-tickets.md) | |
| 28 | -* TODO [Timeline](api-timeline.md) | |
| 29 | -* TODO [User Management](api-users.md) | |
| 30 | -* TODO [Version](api-version.md) | |
| 31 | -* [Wiki](api-wiki.md) |
| --- a/www/json-api/api-index.md | |
| +++ b/www/json-api/api-index.md | |
| @@ -1,31 +0,0 @@ | |
| 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 | * [Authentication](api-auth.md) |
| 18 | * [Branches](api-branch.md) |
| 19 | * [Checkout Status](api-checkout.md) |
| 20 | * [Config](api-config.md) |
| 21 | * [Diffs](api-diff.md) |
| 22 | * [Directory Listing](api-dir.md) |
| 23 | * [File Info](api-finfo.md) |
| 24 | * [Repository Stats](api-stat.md) |
| 25 | * [SQL Query](api-query.md) |
| 26 | * [Tags](api-tag.md) |
| 27 | * TODO [Tickets](api-tickets.md) |
| 28 | * TODO [Timeline](api-timeline.md) |
| 29 | * TODO [User Management](api-users.md) |
| 30 | * TODO [Version](api-version.md) |
| 31 | * [Wiki](api-wiki.md) |
| --- a/www/json-api/api-index.md | |
| +++ b/www/json-api/api-index.md | |
| @@ -1,31 +0,0 @@ | |
+92
| --- a/www/json-api/api-misc.md | ||
| +++ b/www/json-api/api-misc.md | ||
| @@ -0,0 +1,92 @@ | ||
| 1 | +# JSON API: Misc. APIs | |
| 2 | +([⬑JSON API Index](index.md)) | |
| 3 | + | |
| 4 | +Some operations simply don't fit into a specific category (well, none | |
| 5 | +except "misc")... | |
| 6 | + | |
| 7 | +Jump to: | |
| 8 | + | |
| 9 | +* [Global State ("g")](#g) | |
| 10 | +* [Rebuild Repository](#rebuild) | |
| 11 | +* [Result Code Descriptions](#result-codes) | |
| 12 | + | |
| 13 | +--- | |
| 14 | + | |
| 15 | +<a id="g"></a> | |
| 16 | +# Global State ("g") | |
| 17 | + | |
| 18 | +Fossil's internal state is maintained in a global object called "g". And | |
| 19 | +thus this command is named "g"... | |
| 20 | + | |
| 21 | +**Status:** implemented 20111009 | |
| 22 | + | |
| 23 | +**Required permissions:** "a" or "s" | |
| 24 | + | |
| 25 | +**Request:** `/json/g` | |
| 26 | + | |
| 27 | +**Response payload example:** this is a debugging-only request, and has | |
| 28 | +no stable response payload structure. The result object contains all | |
| 29 | +kinds of details gleaned from the fossil environment. | |
| 30 | + | |
| 31 | +Easter egg: this output can be added to ANY response by passing the | |
| 32 | +`debugFossilG` boolean in the POST envelope or GET parameters, or as the | |
| 33 | +`--json-debug-g` flag in CLI mode. This requires admin or setup | |
| 34 | +privileges, though, and it is silently ignored for other users. | |
| 35 | + | |
| 36 | + | |
| 37 | +<a id="rebuild"></a> | |
| 38 | +# Rebuild Repository | |
| 39 | + | |
| 40 | +This request does the same as the "fossil rebuild" command, rebuilding | |
| 41 | +the repo-internal structure. This is often required after upgrading the | |
| 42 | +fossil binary on a system. There "are very probably" cases where calling | |
| 43 | +this over HTTP will not work (e.g. if the user table has changed enough | |
| 44 | +that the access rights cannot be validated without a rebuild, i.e. a | |
| 45 | +chicken/egg scenario). Another consideration is that this request can | |
| 46 | +take a long time to run - rebuilding the fossil repo on my laptop takes | |
| 47 | +about 21 seconds, which is likely longer than the timeout set on an XHR | |
| 48 | +request, meaning that the rebuild transaction will fail. It can safely | |
| 49 | +be run in CLI mode, where timeouts are not normally a concern. As a | |
| 50 | +preliminary benchmark: rebuilding the fossil repo (as of late 2011) | |
| 51 | +takes just over 21 seconds on my 32-bit 1.6GHz netbook. That said, most | |
| 52 | +repos are much smaller and rebuild in under a few seconds. | |
| 53 | + | |
| 54 | +**Status:** implemented 20110929 | |
| 55 | + | |
| 56 | +**Required privileges:** "a" | |
| 57 | + | |
| 58 | +**Request:** `/json/rebuild` | |
| 59 | + | |
| 60 | +Requires admin access rights. | |
| 61 | + | |
| 62 | +**Response payload:** none (response envelope `resultCode` reports failure). | |
| 63 | +Potential TODO: return the amount of time it took to rebuild. | |
| 64 | + | |
| 65 | + | |
| 66 | +<a id="result-codes"></a> | |
| 67 | +# Result Code Descriptions | |
| 68 | + | |
| 69 | +This request returns the full list of result codes documented for | |
| 70 | +Fossil's JSON API. Each result code is returned as an object containing | |
| 71 | +metadata about the result code. | |
| 72 | + | |
| 73 | +**Status:** implemented 20111006 | |
| 74 | + | |
| 75 | +**Required permissions:** none | |
| 76 | + | |
| 77 | +**Request:** `/json/resultCodes` | |
| 78 | + | |
| 79 | +**Response payload example:** | |
| 80 | + | |
| 81 | +```json | |
| 82 | +[{ | |
| 83 | + "resultCode":"FOSSIL-1000", | |
| 84 | + "cSymbol":"FSL_JSON_E_GENERIC", | |
| 85 | + "number":1000, | |
| 86 | + "description":"Generic error" | |
| 87 | + }, | |
| 88 | + … many more objects with the same structure … | |
| 89 | +] | |
| 90 | +``` | |
| 91 | + | |
| 92 | + |
| --- a/www/json-api/api-misc.md | |
| +++ b/www/json-api/api-misc.md | |
| @@ -0,0 +1,92 @@ | |
| --- a/www/json-api/api-misc.md | |
| +++ b/www/json-api/api-misc.md | |
| @@ -0,0 +1,92 @@ | |
| 1 | # JSON API: Misc. APIs |
| 2 | ([⬑JSON API Index](index.md)) |
| 3 | |
| 4 | Some operations simply don't fit into a specific category (well, none |
| 5 | except "misc")... |
| 6 | |
| 7 | Jump to: |
| 8 | |
| 9 | * [Global State ("g")](#g) |
| 10 | * [Rebuild Repository](#rebuild) |
| 11 | * [Result Code Descriptions](#result-codes) |
| 12 | |
| 13 | --- |
| 14 | |
| 15 | <a id="g"></a> |
| 16 | # Global State ("g") |
| 17 | |
| 18 | Fossil's internal state is maintained in a global object called "g". And |
| 19 | thus this command is named "g"... |
| 20 | |
| 21 | **Status:** implemented 20111009 |
| 22 | |
| 23 | **Required permissions:** "a" or "s" |
| 24 | |
| 25 | **Request:** `/json/g` |
| 26 | |
| 27 | **Response payload example:** this is a debugging-only request, and has |
| 28 | no stable response payload structure. The result object contains all |
| 29 | kinds of details gleaned from the fossil environment. |
| 30 | |
| 31 | Easter egg: this output can be added to ANY response by passing the |
| 32 | `debugFossilG` boolean in the POST envelope or GET parameters, or as the |
| 33 | `--json-debug-g` flag in CLI mode. This requires admin or setup |
| 34 | privileges, though, and it is silently ignored for other users. |
| 35 | |
| 36 | |
| 37 | <a id="rebuild"></a> |
| 38 | # Rebuild Repository |
| 39 | |
| 40 | This request does the same as the "fossil rebuild" command, rebuilding |
| 41 | the repo-internal structure. This is often required after upgrading the |
| 42 | fossil binary on a system. There "are very probably" cases where calling |
| 43 | this over HTTP will not work (e.g. if the user table has changed enough |
| 44 | that the access rights cannot be validated without a rebuild, i.e. a |
| 45 | chicken/egg scenario). Another consideration is that this request can |
| 46 | take a long time to run - rebuilding the fossil repo on my laptop takes |
| 47 | about 21 seconds, which is likely longer than the timeout set on an XHR |
| 48 | request, meaning that the rebuild transaction will fail. It can safely |
| 49 | be run in CLI mode, where timeouts are not normally a concern. As a |
| 50 | preliminary benchmark: rebuilding the fossil repo (as of late 2011) |
| 51 | takes just over 21 seconds on my 32-bit 1.6GHz netbook. That said, most |
| 52 | repos are much smaller and rebuild in under a few seconds. |
| 53 | |
| 54 | **Status:** implemented 20110929 |
| 55 | |
| 56 | **Required privileges:** "a" |
| 57 | |
| 58 | **Request:** `/json/rebuild` |
| 59 | |
| 60 | Requires admin access rights. |
| 61 | |
| 62 | **Response payload:** none (response envelope `resultCode` reports failure). |
| 63 | Potential TODO: return the amount of time it took to rebuild. |
| 64 | |
| 65 | |
| 66 | <a id="result-codes"></a> |
| 67 | # Result Code Descriptions |
| 68 | |
| 69 | This request returns the full list of result codes documented for |
| 70 | Fossil's JSON API. Each result code is returned as an object containing |
| 71 | metadata about the result code. |
| 72 | |
| 73 | **Status:** implemented 20111006 |
| 74 | |
| 75 | **Required permissions:** none |
| 76 | |
| 77 | **Request:** `/json/resultCodes` |
| 78 | |
| 79 | **Response payload example:** |
| 80 | |
| 81 | ```json |
| 82 | [{ |
| 83 | "resultCode":"FOSSIL-1000", |
| 84 | "cSymbol":"FSL_JSON_E_GENERIC", |
| 85 | "number":1000, |
| 86 | "description":"Generic error" |
| 87 | }, |
| 88 | … many more objects with the same structure … |
| 89 | ] |
| 90 | ``` |
| 91 | |
| 92 |
+136
| --- a/www/json-api/api-ticket.md | ||
| +++ b/www/json-api/api-ticket.md | ||
| @@ -0,0 +1,136 @@ | ||
| 1 | +# JSON API: Tickets | |
| 2 | +([⬑JSON API Index](index.md)) | |
| 3 | + | |
| 4 | +Jump to: | |
| 5 | + | |
| 6 | +* [Ticket Reports](#reports) | |
| 7 | + * [Fetch a Report](#report-get) | |
| 8 | + * [List Reports](#report-list) | |
| 9 | + * [Run a Report](#report-run) | |
| 10 | + | |
| 11 | + | |
| 12 | +--- | |
| 13 | + | |
| 14 | +# Tickets | |
| 15 | + | |
| 16 | +This API is incomplete. It is missing at least the following features: | |
| 17 | + | |
| 18 | +- Content for a given ticket ID | |
| 19 | +- History for a given ticket ID? | |
| 20 | +- An option to enable/disable the generation of hyperlinks, as links | |
| 21 | + won't be useful in most non-browser clients. | |
| 22 | + | |
| 23 | + | |
| 24 | +<a id="reports"></a> | |
| 25 | +# Ticket Reports | |
| 26 | + | |
| 27 | +<a id="report-get"></a> | |
| 28 | +## Fetch a Report | |
| 29 | + | |
| 30 | +**Status:** implemented 20111008 | |
| 31 | + | |
| 32 | +**Required privileges:** "t" (the thinking being that only those | |
| 33 | +permitted to create reports should be able to read their SQL code) | |
| 34 | + | |
| 35 | +**Request:** `/json/report/get[/REPORT_NUMBER]` | |
| 36 | + | |
| 37 | +**Request options:** | |
| 38 | + | |
| 39 | +- `report=number` The report number to fetch.\ | |
| 40 | + CLI: `-report|-r` \ | |
| 41 | + (Design note: `--number/-n` was not used because that parameter has a | |
| 42 | + different meaning (limit response count) in several commands.) May | |
| 43 | + optionally be defined via the 4th GET path element or CLI arg. | |
| 44 | + | |
| 45 | +**Response payload example:** | |
| 46 | + | |
| 47 | +```json | |
| 48 | +{ | |
| 49 | +"report":1, | |
| 50 | +"owner":"drh", | |
| 51 | +"title":"All Tickets", | |
| 52 | +"timestamp":"112443570187200", | |
| 53 | +"columns":"#ffffff Key:\r\n#f2dcdc Active\r\n...", | |
| 54 | +"sqlCode":"..." | |
| 55 | +} | |
| 56 | +``` | |
| 57 | + | |
| 58 | +<a id="report-list"></a> | |
| 59 | +## List Reports | |
| 60 | + | |
| 61 | +**Status:** implemented 20111008 | |
| 62 | + | |
| 63 | +**Required privileges:** "r" or "n" | |
| 64 | + | |
| 65 | +**Request:** `/json/report/list` | |
| 66 | + | |
| 67 | +**Response payload example:** | |
| 68 | + | |
| 69 | +```json | |
| 70 | +[ | |
| 71 | + { | |
| 72 | + "report":1, | |
| 73 | + "title":"All Tickets", | |
| 74 | + "owner":"drh" | |
| 75 | + }, | |
| 76 | + … | |
| 77 | +] | |
| 78 | +``` | |
| 79 | + | |
| 80 | +<a id="report-run"></a> | |
| 81 | +## Run a Report | |
| 82 | + | |
| 83 | +**Status:** implemented 20111008 | |
| 84 | + | |
| 85 | +**Required privileges:** "r" or "n" | |
| 86 | + | |
| 87 | +**Request:** `/json/report/run[/REPORT_NUMBER]` | |
| 88 | + | |
| 89 | +Request options: | |
| 90 | + | |
| 91 | +- `report|-r=int` Specifies which report to run. May optionally be | |
| 92 | + supplied as the 4th CLI arg or URL path element. | |
| 93 | +- `format|-f=string` (default="o") Specifies "array" or "object" output | |
| 94 | + format. | |
| 95 | + | |
| 96 | +**Response payload example:** | |
| 97 | + | |
| 98 | +```json | |
| 99 | +{ | |
| 100 | + "report":1, | |
| 101 | + "title":"All Tickets", | |
| 102 | + "sqlcode": "only set if requester has 't' privileges.", | |
| 103 | + "columnNames":[ … list of column names … ], | |
| 104 | + "tickets":[ | |
| 105 | + { | |
| 106 | + "bgcolor":"#cfe8bd", | |
| 107 | + "#":"fc825dcf52", | |
| 108 | + "timestamp":"112443570187200", | |
| 109 | + "type":"Code_Defect", | |
| 110 | + "status":"Fixed", | |
| 111 | + "subsystem":null, | |
| 112 | + "title":"\"config pull all\" asks to approve ssl cert" | |
| 113 | + }, | |
| 114 | + … | |
| 115 | + ] | |
| 116 | +} | |
| 117 | +``` | |
| 118 | + | |
| 119 | +Note that the column names of ticket reports are determined by the | |
| 120 | +reports themselves, and not C code. That means that we cannot return a | |
| 121 | +standard set of column names here. Fossil requires certain column naming | |
| 122 | +conventions for purposes of styling the HTML interface, e.g. the "\#" | |
| 123 | +column is always the uuid of the record and "bgcolor" (note the | |
| 124 | +different casing than bgColor used throughout the rest of this API!) has | |
| 125 | +a specific meaning to the HTML report browser. Fossil also allows the | |
| 126 | +tickets to be extended with client-specified fields, so we cannot | |
| 127 | +generically make these results fit into the API-wide naming scheme. Full | |
| 128 | +details are here: | |
| 129 | + | |
| 130 | +[](/doc/trunk/www/custom_ticket.wiki) | |
| 131 | + | |
| 132 | +and: | |
| 133 | + | |
| 134 | +[](/rptsql?rn=1) | |
| 135 | + | |
| 136 | +(That one may require non-default permission.) |
| --- a/www/json-api/api-ticket.md | |
| +++ b/www/json-api/api-ticket.md | |
| @@ -0,0 +1,136 @@ | |
| --- a/www/json-api/api-ticket.md | |
| +++ b/www/json-api/api-ticket.md | |
| @@ -0,0 +1,136 @@ | |
| 1 | # JSON API: Tickets |
| 2 | ([⬑JSON API Index](index.md)) |
| 3 | |
| 4 | Jump to: |
| 5 | |
| 6 | * [Ticket Reports](#reports) |
| 7 | * [Fetch a Report](#report-get) |
| 8 | * [List Reports](#report-list) |
| 9 | * [Run a Report](#report-run) |
| 10 | |
| 11 | |
| 12 | --- |
| 13 | |
| 14 | # Tickets |
| 15 | |
| 16 | This API is incomplete. It is missing at least the following features: |
| 17 | |
| 18 | - Content for a given ticket ID |
| 19 | - History for a given ticket ID? |
| 20 | - An option to enable/disable the generation of hyperlinks, as links |
| 21 | won't be useful in most non-browser clients. |
| 22 | |
| 23 | |
| 24 | <a id="reports"></a> |
| 25 | # Ticket Reports |
| 26 | |
| 27 | <a id="report-get"></a> |
| 28 | ## Fetch a Report |
| 29 | |
| 30 | **Status:** implemented 20111008 |
| 31 | |
| 32 | **Required privileges:** "t" (the thinking being that only those |
| 33 | permitted to create reports should be able to read their SQL code) |
| 34 | |
| 35 | **Request:** `/json/report/get[/REPORT_NUMBER]` |
| 36 | |
| 37 | **Request options:** |
| 38 | |
| 39 | - `report=number` The report number to fetch.\ |
| 40 | CLI: `-report|-r` \ |
| 41 | (Design note: `--number/-n` was not used because that parameter has a |
| 42 | different meaning (limit response count) in several commands.) May |
| 43 | optionally be defined via the 4th GET path element or CLI arg. |
| 44 | |
| 45 | **Response payload example:** |
| 46 | |
| 47 | ```json |
| 48 | { |
| 49 | "report":1, |
| 50 | "owner":"drh", |
| 51 | "title":"All Tickets", |
| 52 | "timestamp":"112443570187200", |
| 53 | "columns":"#ffffff Key:\r\n#f2dcdc Active\r\n...", |
| 54 | "sqlCode":"..." |
| 55 | } |
| 56 | ``` |
| 57 | |
| 58 | <a id="report-list"></a> |
| 59 | ## List Reports |
| 60 | |
| 61 | **Status:** implemented 20111008 |
| 62 | |
| 63 | **Required privileges:** "r" or "n" |
| 64 | |
| 65 | **Request:** `/json/report/list` |
| 66 | |
| 67 | **Response payload example:** |
| 68 | |
| 69 | ```json |
| 70 | [ |
| 71 | { |
| 72 | "report":1, |
| 73 | "title":"All Tickets", |
| 74 | "owner":"drh" |
| 75 | }, |
| 76 | … |
| 77 | ] |
| 78 | ``` |
| 79 | |
| 80 | <a id="report-run"></a> |
| 81 | ## Run a Report |
| 82 | |
| 83 | **Status:** implemented 20111008 |
| 84 | |
| 85 | **Required privileges:** "r" or "n" |
| 86 | |
| 87 | **Request:** `/json/report/run[/REPORT_NUMBER]` |
| 88 | |
| 89 | Request options: |
| 90 | |
| 91 | - `report|-r=int` Specifies which report to run. May optionally be |
| 92 | supplied as the 4th CLI arg or URL path element. |
| 93 | - `format|-f=string` (default="o") Specifies "array" or "object" output |
| 94 | format. |
| 95 | |
| 96 | **Response payload example:** |
| 97 | |
| 98 | ```json |
| 99 | { |
| 100 | "report":1, |
| 101 | "title":"All Tickets", |
| 102 | "sqlcode": "only set if requester has 't' privileges.", |
| 103 | "columnNames":[ … list of column names … ], |
| 104 | "tickets":[ |
| 105 | { |
| 106 | "bgcolor":"#cfe8bd", |
| 107 | "#":"fc825dcf52", |
| 108 | "timestamp":"112443570187200", |
| 109 | "type":"Code_Defect", |
| 110 | "status":"Fixed", |
| 111 | "subsystem":null, |
| 112 | "title":"\"config pull all\" asks to approve ssl cert" |
| 113 | }, |
| 114 | … |
| 115 | ] |
| 116 | } |
| 117 | ``` |
| 118 | |
| 119 | Note that the column names of ticket reports are determined by the |
| 120 | reports themselves, and not C code. That means that we cannot return a |
| 121 | standard set of column names here. Fossil requires certain column naming |
| 122 | conventions for purposes of styling the HTML interface, e.g. the "\#" |
| 123 | column is always the uuid of the record and "bgcolor" (note the |
| 124 | different casing than bgColor used throughout the rest of this API!) has |
| 125 | a specific meaning to the HTML report browser. Fossil also allows the |
| 126 | tickets to be extended with client-specified fields, so we cannot |
| 127 | generically make these results fit into the API-wide naming scheme. Full |
| 128 | details are here: |
| 129 | |
| 130 | [](/doc/trunk/www/custom_ticket.wiki) |
| 131 | |
| 132 | and: |
| 133 | |
| 134 | [](/rptsql?rn=1) |
| 135 | |
| 136 | (That one may require non-default permission.) |
+146
| --- a/www/json-api/api-timeline.md | ||
| +++ b/www/json-api/api-timeline.md | ||
| @@ -0,0 +1,146 @@ | ||
| 1 | +# JSON API: /timeline | |
| 2 | +([⬑JSON API Index](index.md)) | |
| 3 | + | |
| 4 | +Jump to: | |
| 5 | + | |
| 6 | +* [Introduction](#intro) | |
| 7 | +* [Branch Timeline](#branch) | |
| 8 | +* [Technote (formerly Event) Timeline](#technote) | |
| 9 | +* [Ticket Timeline](#ticket) | |
| 10 | +* [Wiki Timeline](#wiki) | |
| 11 | + | |
| 12 | +--- | |
| 13 | + | |
| 14 | +<a id="intro"></a> | |
| 15 | +# Introduction | |
| 16 | + | |
| 17 | +These requests return overview-level information about various types of | |
| 18 | +changes. The response payload differs for each artifact type, and the | |
| 19 | +current structures are almost certainly not "final" (e.g. we are still | |
| 20 | +undecided on how/whether to handle artifact links within commit messages | |
| 21 | +and whatnot). | |
| 22 | + | |
| 23 | +By default the entries are returned in chronological order from newest | |
| 24 | +to oldest, but some options might change that. | |
| 25 | + | |
| 26 | +FIXME (20120623): we have some inconsistent "type" vs. "eventType" is the current preferred choice (and it seems | |
| 27 | +unlikely that `eventType` is actually used in any client code). We | |
| 28 | +don't actually need either one (but a use for "type"r one (but a use for `type` is easily | |
| 29 | +envisioned), and we may get rid of both. | |
| 30 | + | |
| 31 | +**Common request options (via CLI, GET or POST.payloaUUID", "...other parent UUID:** | |
| 32 | + | |
| 33 | +- `limit=integer` limits the number of entries in the response. Default | |
| 34 | + is unspecified (but is "quite possibly 20 or so"). A limit value of | |
| 35 | + 0 disables any limit, fetching all entries (which can take a really | |
| 36 | + long time and might overload clients which have very limited | |
| 37 | + memory).\ | |
| 38 | + CLI mode: `--limit|-n #` | |
| 39 | +- `after="YYYY-MM-DD[ HH:mm:ss]"` limits the search to items on or | |
| 40 | + after the given date string. Reverses the normal timeline sort | |
| 41 | + order. Alias: "a". Only one of "after" or "before" can be used, and | |
| 42 | + if both are specified then which one takes precedence is | |
| 43 | + unspecified.\ | |
| 44 | + CLI mode: `--after|-a "DATE[ TIME]"` | |
| 45 | +- `buuid, previous uuidHH:mm:ss]"` limits the search t\ | |
| 46 | + CLI mode: `-- be ported from the HTML-mode timeline: | |
| 47 | + - circa=DATETIME | |
| 48 | + - tag=string | |
| 49 | + - related=tag name | |
| 50 | + - string=search string | |
| 51 | + | |
| 52 | +<a id="branch"></a> | |
| 53 | +# Branch Timeline | |
| 54 | + | |
| 55 | +**Status:** partially implemented but undocumented because the utility | |
| 56 | +of the current impl is under question. It also doesn't understand most | |
| 57 | +of the common timeline options. | |
| 58 | + | |
| 59 | +<a id="checkin"></a> | |
| 60 | +# Checkin Timeline | |
| 61 | + | |
| 62 | +**Status:** implemented 201109xx | |
| 63 | + | |
| 64 | +**Required privileges:** "o" | |
| 65 | + | |
| 66 | +**Request:** `/json/timeline/checkin` | |
| 67 | + | |
| 68 | +**Response payload example:** | |
| 69 | + | |
| 70 | +```json | |
| 71 | +{ | |
| 72 | +"limit": number, /* if not set, all records are returned */ | |
| 73 | +"timeline":[{ | |
| 74 | + "uuid":"be700e84336941ef1bcd08d676310b75b9070f43", | |
| 75 | + "timestamp":1317094090, | |
| 76 | + "comment":"Added /json/timeline/ci showFiles to ajax test page.", | |
| 77 | + "user":"stephan", | |
| 78 | + "isLeaf":true, | |
| 79 | + "bgColor":null, /* not quite sure why this is null? */ | |
| 80 | + "type":"ci", | |
| 81 | + "parents": ["primary parent hash", "...other parent hashes"], | |
| 82 | + "tags":["json"], | |
| 83 | + "files":[{ | |
| 84 | + "name":"ajax/index.html", | |
| 85 | + "uuid":"9f00773a94cea6191dc3289aa24c0811b6d0d8fe", | |
| 86 | + "parent":"50e337c33c27529e08a7037a8679fb84b976ad0b", | |
| 87 | + "state":"modified" | |
| 88 | + }] | |
| 89 | + },...] | |
| 90 | +} | |
| 91 | +``` | |
| 92 | + | |
| 93 | +(Achtung: the `parents` property was called `prevUuid` prior to 20120316.) | |
| 94 | + | |
| 95 | +The `parents` property lists the checkins which were parents of this | |
| 96 | +commit. The first entry in the array is the "primary parent" - the one | |
| 97 | +which was not involved in a merge with the child. | |
| 98 | + | |
| 99 | +**Request options:** | |
| 100 | + | |
| 101 | +- `files=bool` toggles the addition of a "files" array property which | |
| 102 | + contains objects describing the files changed by the commit, | |
| 103 | + including their hash, previous hash, and state change type | |
| 104 | + (modified, added, or removed). ([“uuid” here means hash][uvh])\ | |
| 105 | + CLI mode: `--show-files|-f` | |
| 106 | +- `tag|branch=string` selects only entries with the given tag or "close | |
| 107 | + to" the given branch. Only one of these may be specified and if both | |
| 108 | + are specified, which one takes precedence is unspecified. If the | |
| 109 | + given tag/branch does not exist, an error responUUIDs for ticketUUID and `ticke the actual ticket’s hash. This is an unfortunate | |
| 110 | +discrepancy vis-a-vis the other timeline enuuid. We may want to swap uuid to mean the ticket uuid anange `uuid` | |
| 111 | +to `commitHash`. | |
| 112 | + | |
| 113 | +<a id="wiki"></a> | |
| 114 | +# Wiki Timeline | |
| 115 | + | |
| 116 | +**Status:** implemented 201109xx | |
| 117 | + | |
| 118 | +**Required privileges:** "j" or "o" | |
| 119 | + | |
| 120 | +**Requests:** | |
| 121 | + | |
| 122 | +- `/json/timeline/wiki` | |
| 123 | +- `/json/wiki/timeline` (alias) | |
| 124 | + | |
| 125 | +**Response payload example:** | |
| 126 | + | |
| 127 | +```json | |
| 128 | +{ | |
| 129 | +"limit": number, /* if not set, all records are returned */ | |
| 130 | +"timeline":[{ | |
| 131 | + "uuid":"4b2026f06eb48eaf187209fcb05ba5438c3b0ef0", | |
| 132 | + "timestamp":1331351121, | |
| 133 | + "comment":"Changes to wiki page [Page3]", | |
| 134 | + "user":"stephan", | |
| 135 | + "eventType":"w" | |
| 136 | + },...] | |
| 137 | +} | |
| 138 | +``` | |
| 139 | + | |
| 140 | +The `uuid` of each entry can be passed to `/json/artifact` or | |
| 141 | +`/json/wiki/get?uuid=...` to fetch the raw page and the hash of the | |
| 142 | +parent version. | |
| 143 | + | |
| 144 | +[uvh]: ../hashes.md#uvh | |
| 145 | +uuid920a", | |
| 146 | + "timestamp":1478 |
| --- a/www/json-api/api-timeline.md | |
| +++ b/www/json-api/api-timeline.md | |
| @@ -0,0 +1,146 @@ | |
| --- a/www/json-api/api-timeline.md | |
| +++ b/www/json-api/api-timeline.md | |
| @@ -0,0 +1,146 @@ | |
| 1 | # JSON API: /timeline |
| 2 | ([⬑JSON API Index](index.md)) |
| 3 | |
| 4 | Jump to: |
| 5 | |
| 6 | * [Introduction](#intro) |
| 7 | * [Branch Timeline](#branch) |
| 8 | * [Technote (formerly Event) Timeline](#technote) |
| 9 | * [Ticket Timeline](#ticket) |
| 10 | * [Wiki Timeline](#wiki) |
| 11 | |
| 12 | --- |
| 13 | |
| 14 | <a id="intro"></a> |
| 15 | # Introduction |
| 16 | |
| 17 | These requests return overview-level information about various types of |
| 18 | changes. The response payload differs for each artifact type, and the |
| 19 | current structures are almost certainly not "final" (e.g. we are still |
| 20 | undecided on how/whether to handle artifact links within commit messages |
| 21 | and whatnot). |
| 22 | |
| 23 | By default the entries are returned in chronological order from newest |
| 24 | to oldest, but some options might change that. |
| 25 | |
| 26 | FIXME (20120623): we have some inconsistent "type" vs. "eventType" is the current preferred choice (and it seems |
| 27 | unlikely that `eventType` is actually used in any client code). We |
| 28 | don't actually need either one (but a use for "type"r one (but a use for `type` is easily |
| 29 | envisioned), and we may get rid of both. |
| 30 | |
| 31 | **Common request options (via CLI, GET or POST.payloaUUID", "...other parent UUID:** |
| 32 | |
| 33 | - `limit=integer` limits the number of entries in the response. Default |
| 34 | is unspecified (but is "quite possibly 20 or so"). A limit value of |
| 35 | 0 disables any limit, fetching all entries (which can take a really |
| 36 | long time and might overload clients which have very limited |
| 37 | memory).\ |
| 38 | CLI mode: `--limit|-n #` |
| 39 | - `after="YYYY-MM-DD[ HH:mm:ss]"` limits the search to items on or |
| 40 | after the given date string. Reverses the normal timeline sort |
| 41 | order. Alias: "a". Only one of "after" or "before" can be used, and |
| 42 | if both are specified then which one takes precedence is |
| 43 | unspecified.\ |
| 44 | CLI mode: `--after|-a "DATE[ TIME]"` |
| 45 | - `buuid, previous uuidHH:mm:ss]"` limits the search t\ |
| 46 | CLI mode: `-- be ported from the HTML-mode timeline: |
| 47 | - circa=DATETIME |
| 48 | - tag=string |
| 49 | - related=tag name |
| 50 | - string=search string |
| 51 | |
| 52 | <a id="branch"></a> |
| 53 | # Branch Timeline |
| 54 | |
| 55 | **Status:** partially implemented but undocumented because the utility |
| 56 | of the current impl is under question. It also doesn't understand most |
| 57 | of the common timeline options. |
| 58 | |
| 59 | <a id="checkin"></a> |
| 60 | # Checkin Timeline |
| 61 | |
| 62 | **Status:** implemented 201109xx |
| 63 | |
| 64 | **Required privileges:** "o" |
| 65 | |
| 66 | **Request:** `/json/timeline/checkin` |
| 67 | |
| 68 | **Response payload example:** |
| 69 | |
| 70 | ```json |
| 71 | { |
| 72 | "limit": number, /* if not set, all records are returned */ |
| 73 | "timeline":[{ |
| 74 | "uuid":"be700e84336941ef1bcd08d676310b75b9070f43", |
| 75 | "timestamp":1317094090, |
| 76 | "comment":"Added /json/timeline/ci showFiles to ajax test page.", |
| 77 | "user":"stephan", |
| 78 | "isLeaf":true, |
| 79 | "bgColor":null, /* not quite sure why this is null? */ |
| 80 | "type":"ci", |
| 81 | "parents": ["primary parent hash", "...other parent hashes"], |
| 82 | "tags":["json"], |
| 83 | "files":[{ |
| 84 | "name":"ajax/index.html", |
| 85 | "uuid":"9f00773a94cea6191dc3289aa24c0811b6d0d8fe", |
| 86 | "parent":"50e337c33c27529e08a7037a8679fb84b976ad0b", |
| 87 | "state":"modified" |
| 88 | }] |
| 89 | },...] |
| 90 | } |
| 91 | ``` |
| 92 | |
| 93 | (Achtung: the `parents` property was called `prevUuid` prior to 20120316.) |
| 94 | |
| 95 | The `parents` property lists the checkins which were parents of this |
| 96 | commit. The first entry in the array is the "primary parent" - the one |
| 97 | which was not involved in a merge with the child. |
| 98 | |
| 99 | **Request options:** |
| 100 | |
| 101 | - `files=bool` toggles the addition of a "files" array property which |
| 102 | contains objects describing the files changed by the commit, |
| 103 | including their hash, previous hash, and state change type |
| 104 | (modified, added, or removed). ([“uuid” here means hash][uvh])\ |
| 105 | CLI mode: `--show-files|-f` |
| 106 | - `tag|branch=string` selects only entries with the given tag or "close |
| 107 | to" the given branch. Only one of these may be specified and if both |
| 108 | are specified, which one takes precedence is unspecified. If the |
| 109 | given tag/branch does not exist, an error responUUIDs for ticketUUID and `ticke the actual ticket’s hash. This is an unfortunate |
| 110 | discrepancy vis-a-vis the other timeline enuuid. We may want to swap uuid to mean the ticket uuid anange `uuid` |
| 111 | to `commitHash`. |
| 112 | |
| 113 | <a id="wiki"></a> |
| 114 | # Wiki Timeline |
| 115 | |
| 116 | **Status:** implemented 201109xx |
| 117 | |
| 118 | **Required privileges:** "j" or "o" |
| 119 | |
| 120 | **Requests:** |
| 121 | |
| 122 | - `/json/timeline/wiki` |
| 123 | - `/json/wiki/timeline` (alias) |
| 124 | |
| 125 | **Response payload example:** |
| 126 | |
| 127 | ```json |
| 128 | { |
| 129 | "limit": number, /* if not set, all records are returned */ |
| 130 | "timeline":[{ |
| 131 | "uuid":"4b2026f06eb48eaf187209fcb05ba5438c3b0ef0", |
| 132 | "timestamp":1331351121, |
| 133 | "comment":"Changes to wiki page [Page3]", |
| 134 | "user":"stephan", |
| 135 | "eventType":"w" |
| 136 | },...] |
| 137 | } |
| 138 | ``` |
| 139 | |
| 140 | The `uuid` of each entry can be passed to `/json/artifact` or |
| 141 | `/json/wiki/get?uuid=...` to fetch the raw page and the hash of the |
| 142 | parent version. |
| 143 | |
| 144 | [uvh]: ../hashes.md#uvh |
| 145 | uuid920a", |
| 146 | "timestamp":1478 |
+142
| --- a/www/json-api/api-user.md | ||
| +++ b/www/json-api/api-user.md | ||
| @@ -0,0 +1,142 @@ | ||
| 1 | +# JSON API: /user | |
| 2 | +([⬑JSON API Index](index.md)) | |
| 3 | + | |
| 4 | +Jump to: | |
| 5 | + | |
| 6 | +* [Get User Info](#get) | |
| 7 | +* [List Users](#list) | |
| 8 | +* [Save User](#save) | |
| 9 | + | |
| 10 | +--- | |
| 11 | + | |
| 12 | +<a id="get"></a> | |
| 13 | +# Get User Info | |
| 14 | + | |
| 15 | +**Status:** implemented 20110927. | |
| 16 | + | |
| 17 | +**Required privileges:** "a" or "s" | |
| 18 | + | |
| 19 | +**Request:** | |
| 20 | + | |
| 21 | +- POST `/json/user/get`\ | |
| 22 | + with `POST.payload.name=USERNAME` | |
| 23 | +- `/json/user/get?name=USERNAME` | |
| 24 | + | |
| 25 | +**Response payload example:** | |
| 26 | + | |
| 27 | +```json | |
| 28 | +{ | |
| 29 | + "uid":1, | |
| 30 | + "name":"stephan", | |
| 31 | + "capabilities":"abcdefhgijkmnopqrstuvwxz", | |
| 32 | + "info":"https://wanderinghorse.net/home/stephan/", | |
| 33 | + "timestamp":1316122562 | |
| 34 | +} | |
| 35 | +``` | |
| 36 | + | |
| 37 | +(What does that timestamp field represent, anyway?) | |
| 38 | + | |
| 39 | +<a id="list"></a> | |
| 40 | +# List Users | |
| 41 | + | |
| 42 | +**Status:** implemented 20110927. | |
| 43 | + | |
| 44 | +**Required privileges:** "a" or "s" | |
| 45 | + | |
| 46 | +**Request:** `/json/user/list` | |
| 47 | + | |
| 48 | +**Response payload example:** | |
| 49 | + | |
| 50 | +```json | |
| 51 | +[ | |
| 52 | + { | |
| 53 | + "uid":1, | |
| 54 | + "name":"stephan", | |
| 55 | + "capabilities":"abcdefhgijkmnoprstuvwxz", | |
| 56 | + "info":"", | |
| 57 | + "timestamp":1316122562 | |
| 58 | + }, | |
| 59 | + ... more users... | |
| 60 | +] | |
| 61 | +``` | |
| 62 | + | |
| 63 | + | |
| 64 | +<a id="save"></a> | |
| 65 | +# Save User | |
| 66 | + | |
| 67 | +Only admin/setup users may modify accounts other than their own. | |
| 68 | + | |
| 69 | +**Status:** implemented 20111021 *but* it is missing "login group" | |
| 70 | +support, so changes do not yet propagate to other repos within a group. | |
| 71 | + | |
| 72 | +**Required privileges:** 'p' or 'a' or 's', depending on the context. | |
| 73 | + | |
| 74 | +**Request:** `/json/user/save` | |
| 75 | + | |
| 76 | +All request options must come from the `POST.payload` and/or GET/CLI | |
| 77 | +parameters (exception: "name" must come from POST.payload or CLI). | |
| 78 | +GET/CLI parameters take precedence over those in `POST.payload`, the | |
| 79 | +intention being to use an input file as a template and overriding the | |
| 80 | +template's defaults via the CLI. The options include: | |
| 81 | + | |
| 82 | +- `name=string` Specifies the user name to change. When changing a | |
| 83 | + user's name, the current uid and the new name must be specified.\ | |
| 84 | + **Achtung:** due to fossil-internal ambiguity in the handling of the | |
| 85 | + "name" parameter, this parameter must come from the `POST.payload` | |
| 86 | + data or it will not be recognized. In CLI mode it may be specified | |
| 87 | + with the `--name` flag. | |
| 88 | +- `uid=int` Specifies the uid to change. At least one of uid or name are | |
| 89 | + required. A uid of -1 means to create a new user, in which case the | |
| 90 | + name must be provided. | |
| 91 | +- `password=string` Optionally changes the user's password. When | |
| 92 | + renaming existing or creating new users, be sure to always provide a | |
| 93 | + new password because any old password hash is invalidated by the | |
| 94 | + name change. | |
| 95 | +- `info=string` Optionally changes the user's info field. | |
| 96 | +- `capabilities=string` Optionally changes the user's capabilities | |
| 97 | + field. | |
| 98 | +- `forceLogout=bool` (=false, or true when renaming) Optionally clears | |
| 99 | + any current login info for the current user, which will invalidate | |
| 100 | + any active session. Requires 'a' or 's' privileges. Intended to be | |
| 101 | + used when disabling a user account, to ensure that any open session | |
| 102 | + is invalidated. When a user is renamed this option is implied (and | |
| 103 | + cannot be disabled) because renaming invalidates any currently | |
| 104 | + stored auth token (because the old name is part of the hash | |
| 105 | + equation). | |
| 106 | + | |
| 107 | +Fields which are not provided in the request will not be modified. | |
| 108 | +Non-admin/setup users cannot edit other users and may only change their | |
| 109 | +own data if they have the 'p' (password) privilege. | |
| 110 | + | |
| 111 | +As of 20120217, users who do not have the setup privilege may neither | |
| 112 | +change the setup privilege for any user nor edit another user who has | |
| 113 | +that privilege. That is, only users with setup access may propagate or | |
| 114 | +remove setup status and accounts with the setup privilege may only be | |
| 115 | +edited by themselves and other setup users. | |
| 116 | + | |
| 117 | +**Response payload:** Same as user/get, using the new/saved state of the | |
| 118 | +modified user. | |
| 119 | + | |
| 120 | +Example usage from the command line: | |
| 121 | + | |
| 122 | +```console | |
| 123 | +$ fossil json user save --name drh --password sqlite3 \ | |
| 124 | + --capabilities "as" --info "DRH" | |
| 125 | +$ fossil json user save --uid 1 --name richard \ | |
| 126 | + --password fossil \ | |
| 127 | + --info "Previously known as drh" | |
| 128 | +``` | |
| 129 | + | |
| 130 | +**Warnings:** | |
| 131 | + | |
| 132 | +- When creating a new user or renaming a user, if no (new) password is | |
| 133 | + specified in the save request then the user will not be able to log | |
| 134 | + in because the previous password (for existing users) is hashed | |
| 135 | + against the old name. | |
| 136 | +- Renaming a user invalidates any active login token because his old | |
| 137 | + name is a part of the hash. i.e. the user must log back in with the | |
| 138 | + new name after being renamed. | |
| 139 | + | |
| 140 | +**TODOs:** | |
| 141 | + | |
| 142 | +- Login group support. |
| --- a/www/json-api/api-user.md | |
| +++ b/www/json-api/api-user.md | |
| @@ -0,0 +1,142 @@ | |
| --- a/www/json-api/api-user.md | |
| +++ b/www/json-api/api-user.md | |
| @@ -0,0 +1,142 @@ | |
| 1 | # JSON API: /user |
| 2 | ([⬑JSON API Index](index.md)) |
| 3 | |
| 4 | Jump to: |
| 5 | |
| 6 | * [Get User Info](#get) |
| 7 | * [List Users](#list) |
| 8 | * [Save User](#save) |
| 9 | |
| 10 | --- |
| 11 | |
| 12 | <a id="get"></a> |
| 13 | # Get User Info |
| 14 | |
| 15 | **Status:** implemented 20110927. |
| 16 | |
| 17 | **Required privileges:** "a" or "s" |
| 18 | |
| 19 | **Request:** |
| 20 | |
| 21 | - POST `/json/user/get`\ |
| 22 | with `POST.payload.name=USERNAME` |
| 23 | - `/json/user/get?name=USERNAME` |
| 24 | |
| 25 | **Response payload example:** |
| 26 | |
| 27 | ```json |
| 28 | { |
| 29 | "uid":1, |
| 30 | "name":"stephan", |
| 31 | "capabilities":"abcdefhgijkmnopqrstuvwxz", |
| 32 | "info":"https://wanderinghorse.net/home/stephan/", |
| 33 | "timestamp":1316122562 |
| 34 | } |
| 35 | ``` |
| 36 | |
| 37 | (What does that timestamp field represent, anyway?) |
| 38 | |
| 39 | <a id="list"></a> |
| 40 | # List Users |
| 41 | |
| 42 | **Status:** implemented 20110927. |
| 43 | |
| 44 | **Required privileges:** "a" or "s" |
| 45 | |
| 46 | **Request:** `/json/user/list` |
| 47 | |
| 48 | **Response payload example:** |
| 49 | |
| 50 | ```json |
| 51 | [ |
| 52 | { |
| 53 | "uid":1, |
| 54 | "name":"stephan", |
| 55 | "capabilities":"abcdefhgijkmnoprstuvwxz", |
| 56 | "info":"", |
| 57 | "timestamp":1316122562 |
| 58 | }, |
| 59 | ... more users... |
| 60 | ] |
| 61 | ``` |
| 62 | |
| 63 | |
| 64 | <a id="save"></a> |
| 65 | # Save User |
| 66 | |
| 67 | Only admin/setup users may modify accounts other than their own. |
| 68 | |
| 69 | **Status:** implemented 20111021 *but* it is missing "login group" |
| 70 | support, so changes do not yet propagate to other repos within a group. |
| 71 | |
| 72 | **Required privileges:** 'p' or 'a' or 's', depending on the context. |
| 73 | |
| 74 | **Request:** `/json/user/save` |
| 75 | |
| 76 | All request options must come from the `POST.payload` and/or GET/CLI |
| 77 | parameters (exception: "name" must come from POST.payload or CLI). |
| 78 | GET/CLI parameters take precedence over those in `POST.payload`, the |
| 79 | intention being to use an input file as a template and overriding the |
| 80 | template's defaults via the CLI. The options include: |
| 81 | |
| 82 | - `name=string` Specifies the user name to change. When changing a |
| 83 | user's name, the current uid and the new name must be specified.\ |
| 84 | **Achtung:** due to fossil-internal ambiguity in the handling of the |
| 85 | "name" parameter, this parameter must come from the `POST.payload` |
| 86 | data or it will not be recognized. In CLI mode it may be specified |
| 87 | with the `--name` flag. |
| 88 | - `uid=int` Specifies the uid to change. At least one of uid or name are |
| 89 | required. A uid of -1 means to create a new user, in which case the |
| 90 | name must be provided. |
| 91 | - `password=string` Optionally changes the user's password. When |
| 92 | renaming existing or creating new users, be sure to always provide a |
| 93 | new password because any old password hash is invalidated by the |
| 94 | name change. |
| 95 | - `info=string` Optionally changes the user's info field. |
| 96 | - `capabilities=string` Optionally changes the user's capabilities |
| 97 | field. |
| 98 | - `forceLogout=bool` (=false, or true when renaming) Optionally clears |
| 99 | any current login info for the current user, which will invalidate |
| 100 | any active session. Requires 'a' or 's' privileges. Intended to be |
| 101 | used when disabling a user account, to ensure that any open session |
| 102 | is invalidated. When a user is renamed this option is implied (and |
| 103 | cannot be disabled) because renaming invalidates any currently |
| 104 | stored auth token (because the old name is part of the hash |
| 105 | equation). |
| 106 | |
| 107 | Fields which are not provided in the request will not be modified. |
| 108 | Non-admin/setup users cannot edit other users and may only change their |
| 109 | own data if they have the 'p' (password) privilege. |
| 110 | |
| 111 | As of 20120217, users who do not have the setup privilege may neither |
| 112 | change the setup privilege for any user nor edit another user who has |
| 113 | that privilege. That is, only users with setup access may propagate or |
| 114 | remove setup status and accounts with the setup privilege may only be |
| 115 | edited by themselves and other setup users. |
| 116 | |
| 117 | **Response payload:** Same as user/get, using the new/saved state of the |
| 118 | modified user. |
| 119 | |
| 120 | Example usage from the command line: |
| 121 | |
| 122 | ```console |
| 123 | $ fossil json user save --name drh --password sqlite3 \ |
| 124 | --capabilities "as" --info "DRH" |
| 125 | $ fossil json user save --uid 1 --name richard \ |
| 126 | --password fossil \ |
| 127 | --info "Previously known as drh" |
| 128 | ``` |
| 129 | |
| 130 | **Warnings:** |
| 131 | |
| 132 | - When creating a new user or renaming a user, if no (new) password is |
| 133 | specified in the save request then the user will not be able to log |
| 134 | in because the previous password (for existing users) is hashed |
| 135 | against the old name. |
| 136 | - Renaming a user invalidates any active login token because his old |
| 137 | name is a part of the hash. i.e. the user must log back in with the |
| 138 | new name after being renamed. |
| 139 | |
| 140 | **TODOs:** |
| 141 | |
| 142 | - Login group support. |
| --- a/www/json-api/api-version.md | ||
| +++ b/www/json-api/api-version.md | ||
| @@ -0,0 +1,32 @@ | ||
| 1 | +# JSON API: /version | |
| 2 | +([⬑JSON API Index](index.md)) | |
| 3 | + | |
| 4 | +# Version (a.k.a. HAI) | |
| 5 | + | |
| 6 | +**Status:** implemented | |
| 7 | + | |
| 8 | +**Required privileges:** none | |
| 9 | + | |
| 10 | +**Requests:** | |
| 11 | + | |
| 12 | +- `/json/version` | |
| 13 | +- `/json/HAI` (alias borrowed from LOLCATZ jargon) | |
| 14 | + | |
| 15 | +**Response payload example:** | |
| 16 | + | |
| 17 | +```json | |
| 18 | +{ | |
| 19 | +"manifestUuid":"20ff808f9809541d2eca6c49a17d5cbd16e1b93f", | |
| 20 | +"manifestVersion":"[20ff808f98]", | |
| 21 | +"manifestDate":"2011-09-09 16:49:23", | |
| 22 | +"manifestYear":"2011", | |
| 23 | +"releaseVersion":"1.19", | |
| 24 | +"releaseVersionNumber":119, | |
| 25 | +"jsonApiVersion": "YYYYMMDD" // added 20120409 | |
| 26 | +} | |
| 27 | +``` | |
| 28 | + | |
| 29 | +Those particular payload fields were chosen only because they're defined | |
| 30 | +in `VERSION.h`. We may want to add other information, but nothing comes to | |
| 31 | +mind at this time. | |
| 32 | + |
| --- a/www/json-api/api-version.md | |
| +++ b/www/json-api/api-version.md | |
| @@ -0,0 +1,32 @@ | |
| --- a/www/json-api/api-version.md | |
| +++ b/www/json-api/api-version.md | |
| @@ -0,0 +1,32 @@ | |
| 1 | # JSON API: /version |
| 2 | ([⬑JSON API Index](index.md)) |
| 3 | |
| 4 | # Version (a.k.a. HAI) |
| 5 | |
| 6 | **Status:** implemented |
| 7 | |
| 8 | **Required privileges:** none |
| 9 | |
| 10 | **Requests:** |
| 11 | |
| 12 | - `/json/version` |
| 13 | - `/json/HAI` (alias borrowed from LOLCATZ jargon) |
| 14 | |
| 15 | **Response payload example:** |
| 16 | |
| 17 | ```json |
| 18 | { |
| 19 | "manifestUuid":"20ff808f9809541d2eca6c49a17d5cbd16e1b93f", |
| 20 | "manifestVersion":"[20ff808f98]", |
| 21 | "manifestDate":"2011-09-09 16:49:23", |
| 22 | "manifestYear":"2011", |
| 23 | "releaseVersion":"1.19", |
| 24 | "releaseVersionNumber":119, |
| 25 | "jsonApiVersion": "YYYYMMDD" // added 20120409 |
| 26 | } |
| 27 | ``` |
| 28 | |
| 29 | Those particular payload fields were chosen only because they're defined |
| 30 | in `VERSION.h`. We may want to add other information, but nothing comes to |
| 31 | mind at this time. |
| 32 |
+214
-424
| --- www/json-api/conventions.md | ||
| +++ www/json-api/conventions.md | ||
| @@ -3,11 +3,12 @@ | ||
| 3 | 3 | |
| 4 | 4 | Jump to: |
| 5 | 5 | |
| 6 | 6 | * [JSON Property Naming](#property-names) |
| 7 | 7 | * [HTTP GET Requests](#http-get) |
| 8 | -* [HTTP Post Requests](#http-post) | |
| 8 | +* [HTTP POST Requests](#http-post) | |
| 9 | + * [POST Request Envelope](#request-envelope) | |
| 9 | 10 | * [Request Parameter Data Types](#request-param-types) |
| 10 | 11 | * [Response Envelope](#response-envelope) |
| 11 | 12 | * [HTTP Response Headers](#http-response-header) |
| 12 | 13 | * [CLI vs. HTTP Mode](#cli-vs-http) |
| 13 | 14 | * [Simulating POSTed data](#simulating-post-data) |
| @@ -27,22 +28,23 @@ | ||
| 27 | 28 | |
| 28 | 29 | <a id="http-get"></a> |
| 29 | 30 | # HTTP GET Requests |
| 30 | 31 | |
| 31 | 32 | Many (if not most) requests can be made via simple GET requests, e.g. we |
| 32 | -*could* use any of the following: | |
| 33 | +*could* use any of the following patterns for a hypothetical JSON-format | |
| 34 | +timeline: | |
| 33 | 35 | |
| 34 | -- `http://..../timeline/json` | |
| 36 | +- `https://..../timeline/json` | |
| 35 | 37 | - `/timeline?format=json` |
| 36 | 38 | - `/timeline?json=1` |
| 37 | 39 | - `/timeline.json` |
| 38 | 40 | - `/json/timeline?...options...` |
| 39 | 41 | |
| 40 | -After several discussions, the API settled on the `/json/...` convention, | |
| 41 | -primarily because it simplifies dispatching and argument-handling logic | |
| 42 | -compared to the `/[.../]foo.json` approach. Using `/json/...` allows us | |
| 43 | -to unify that logic for all JSON sub-commands, for both CLI and HTTP modes. | |
| 42 | +The API settled on the `/json/...` convention, primarily because it | |
| 43 | +simplifies dispatching and argument-handling logic compared to the | |
| 44 | +`/[.../]foo.json` approach. Using `/json/...` allows us to unify that | |
| 45 | +logic for all JSON sub-commands, for both CLI and HTTP modes. | |
| 44 | 46 | |
| 45 | 47 | <a id="http-post"></a> |
| 46 | 48 | # HTTP Post Requests |
| 47 | 49 | |
| 48 | 50 | Certain requests, mainly things like editing checkin messages and |
| @@ -56,86 +58,42 @@ | ||
| 56 | 58 | |
| 57 | 59 | POST requests are sent to the same URL as their GET counterpart (if any, |
| 58 | 60 | else their own path), and are sent as plain-text/unencoded JSON wrapped |
| 59 | 61 | in a common request envelope with the following properties: |
| 60 | 62 | |
| 61 | -(TODO: convert to a simple list...) | |
| 62 | -``` | |
| 63 | -+-----------------------------------+-----------------------------------+ | |
| 64 | -| requestId | Optional arbitrary JSON value, | | |
| 65 | -| | not used by fossil, but returned | | |
| 66 | -| | as-is in responses. | | |
| 67 | -+-----------------------------------+-----------------------------------+ | |
| 68 | -| command | Provides a secondary mechanism | | |
| 69 | -| | for specifying which JSON command | | |
| 70 | -| | should be run. A request path of | | |
| 71 | -| | /json/foo/bar is equivalent to a | | |
| 72 | -| | request with path=/json and | | |
| 73 | -| | command=foo/bar. Note that | | |
| 74 | -| | subpaths do *not* work this way. | | |
| 75 | -| | e.g. path=/json/foo, command=bar | | |
| 76 | -| | will not work, but path=/json, | | |
| 77 | -| | command=foo/bar will. | | |
| 78 | -| | | | |
| 79 | -| | This option is particularly | | |
| 80 | -| | useful when generating JSON for | | |
| 81 | -| | piping in to CLI mode, but it | | |
| 82 | -| | also has some | | |
| 83 | -| | response-dispatching uses on the | | |
| 84 | -| | client side. | | |
| 85 | -+-----------------------------------+-----------------------------------+ | |
| 86 | -| authToken | Authentication token. Created by | | |
| 87 | -| | a login request. Determines what | | |
| 88 | -| | access rights the user has, and | | |
| 89 | -| | any given request may require | | |
| 90 | -| | specific rights. In principle | | |
| 91 | -| | this is required by any request | | |
| 92 | -| | which needs non-guest privileges, | | |
| 93 | -| | but cookie-aware clients do not | | |
| 94 | -| | manually need to track this (it | | |
| 95 | -| | is managed as a cookie by the | | |
| 96 | -| | agent/browser). | | |
| 97 | -+-----------------------------------+-----------------------------------+ | |
| 98 | -| payload | Command-specific parameters. Most | | |
| 99 | -| | can optionally come in via GET | | |
| 100 | -| | parameters, but those taking | | |
| 101 | -| | complex structures expect them to | | |
| 102 | -| | be placed here. | | |
| 103 | -+-----------------------------------+-----------------------------------+ | |
| 104 | -| indent | Optionally specifies indentation | | |
| 105 | -| | for the output. 0=no indention. | | |
| 106 | -| | 1=a single TAB character for each | | |
| 107 | -| | level of indentation. >1 means | | |
| 108 | -| | that many *spaces* per level. | | |
| 109 | -| | e.g. indent=7 means to indent 7 | | |
| 110 | -| | spaces per object/array depth | | |
| 111 | -| | level. cson also supports other | | |
| 112 | -| | flags for fine-tuning the output | | |
| 113 | -| | spacing, and adding them to this | | |
| 114 | -| | interface might be interesting at | | |
| 115 | -| | some point. e.g. whether or not | | |
| 116 | -| | to add a newline to the output.\ | | |
| 117 | -| | CLI mode adds extra indentation | | |
| 118 | -| | by default, whereas CGI/server | | |
| 119 | -| | modes produce unindented output | | |
| 120 | -| | by default. | | |
| 121 | -+-----------------------------------+-----------------------------------+ | |
| 122 | -| jsonp | Optional String (client function | | |
| 123 | -| | name). | | |
| 124 | -| | | | |
| 125 | -| | Requests which include this will | | |
| 126 | -| | be returned with Content-Type | | |
| 127 | -| | application/javascript and will | | |
| 128 | -| | be wrapped up in a function call | | |
| 129 | -| | using the given name. e.g. if | | |
| 130 | -| | jsonp=foo then the result would | | |
| 131 | -| | look like: | | |
| 132 | -| | | | |
| 133 | -| | foo( {...the response | | |
| 134 | -| | envelope...} ) | | |
| 135 | -+-----------------------------------+-----------------------------------+ | |
| 136 | -``` | |
| 63 | +- `requestId`: Optional arbitrary JSON value, not used by fossil, but | |
| 64 | + returned as-is in responses. | |
| 65 | +- `command`: Provides a secondary mechanism for specifying which JSON | |
| 66 | + command should be run. A request path of /json/foo/bar is equivalent | |
| 67 | + to a request with path=/json and command=foo/bar. Note that subpaths | |
| 68 | + do not work this way. e.g. path=/json/foo, command=bar will not | |
| 69 | + work, but path=/json, command=foo/bar will. This option is | |
| 70 | + particularly useful when generating JSON for piping in to CLI mode, | |
| 71 | + but it also has some response-dispatching uses on the client side. | |
| 72 | +- `authToken`: Authentication token. Created by a login | |
| 73 | + request. Determines what access rights the user has, and any given | |
| 74 | + request may require specific rights. In principle this is required | |
| 75 | + by any request which needs non-guest privileges, but cookie-aware | |
| 76 | + clients do not manually need to track this (it is managed as a | |
| 77 | + cookie by the agent/browser). | |
| 78 | +- `payload`: Command-specific parameters. Most can optionally come in | |
| 79 | + via GET parameters, but those taking complex structures expect them | |
| 80 | + to be placed here. | |
| 81 | +- `indent`: Optionally specifies indentation for the output. 0=no | |
| 82 | + indention. 1=a single TAB character for each level of | |
| 83 | + indentation. >1 means that many spaces per level. e.g. indent=7 | |
| 84 | + means to indent 7 spaces per object/array depth level. cson also | |
| 85 | + supports other flags for fine-tuning the output spacing, and adding | |
| 86 | + them to this interface might be interesting at some | |
| 87 | + point. e.g. whether or not to add a newline to the output. CLI mode | |
| 88 | + adds extra indentation by default, whereas CGI/server modes produce | |
| 89 | + unindented output by default. | |
| 90 | +- `jsonp`: Optional String (client function name). Requests which | |
| 91 | + include this will be returned with `Content-Type | |
| 92 | + application/javascript` and will be wrapped up in a function call | |
| 93 | + using the given name. e.g. if `jsonp=foo` then the result would look like:\ | |
| 94 | +`foo( {...the response envelope...} )` | |
| 137 | 95 | |
| 138 | 96 | The API allows most of those (normally all but the payload) to come in |
| 139 | 97 | as either GET parameters or properties of the top-level POSTed request |
| 140 | 98 | JSON envelope, with GET taking priority over POST. (Reminder to self: we |
| 141 | 99 | could potentially also use values from cookies. Fossil currently only |
| @@ -180,16 +138,17 @@ | ||
| 180 | 138 | } |
| 181 | 139 | } |
| 182 | 140 | ``` |
| 183 | 141 | |
| 184 | 142 | When a given parameter is set in two places, e.g. GET and POST, or |
| 185 | -POST-from-a-file and CLI parameters, which one takes precedence depends | |
| 186 | -on the concrete command handler (and may be unspecified). Most will give | |
| 187 | -precedence to CLI and GET parameters, but POSTed values are technically | |
| 188 | -preferred for non-string data because no additional "type guessing" or | |
| 189 | -string-to-whatever conversion has to be made (GET/CLI parameters are | |
| 190 | -*always* strings, even if they look like a number or boolean). | |
| 143 | +POST-from-a-file and CLI parameters, which one takes precedence | |
| 144 | +depends on the concrete command handler (and may be unspecified). Most | |
| 145 | +will give precedence to CLI and GET parameters, but POSTed values are | |
| 146 | +technically preferred for non-string data because no additional "type | |
| 147 | +guessing" or string-to-whatever conversion has to be made (GET/CLI | |
| 148 | +parameters are *always* strings, even if they look like a number or | |
| 149 | +boolean). | |
| 191 | 150 | |
| 192 | 151 | |
| 193 | 152 | <a id="request-param-types"></a> |
| 194 | 153 | # Request Parameter Data Types |
| 195 | 154 | |
| @@ -245,140 +204,71 @@ | ||
| 245 | 204 | |
| 246 | 205 | Every response comes in the form of a HTTP response or (in CLI mode) |
| 247 | 206 | JSON sent to stdout. The body of the response is a JSON object following |
| 248 | 207 | a common envelope format. The envelope has the following properties: |
| 249 | 208 | |
| 250 | -(TODO: convert to a simple list...) | |
| 251 | -``` | |
| 252 | -+-----------------------------------+-----------------------------------+ | |
| 253 | -| fossil | Fossil server version string. | | |
| 254 | -| | This property is basically "the | | |
| 255 | -| | official response envelope | | |
| 256 | -| | marker" - if it is set, clients | | |
| 257 | -| | can "probably safely assume" that | | |
| 258 | -| | the object indeed came from one | | |
| 259 | -| | of the Fossil/JSON APIs. This API | | |
| 260 | -| | never creates responses which do | | |
| 261 | -| | not contain this property. | | |
| 262 | -+-----------------------------------+-----------------------------------+ | |
| 263 | -| requestId | Only set if the request contained | | |
| 264 | -| | it, and then it is echoed back to | | |
| 265 | -| | the caller as-is. This can be use | | |
| 266 | -| | to determine (client-side) which | | |
| 267 | -| | request a given response is | | |
| 268 | -| | coming in for (assuming multiple | | |
| 269 | -| | asynchronous requests are | | |
| 270 | -| | pending). In practice this | | |
| 271 | -| | generally isn’t needed because | | |
| 272 | -| | response handling tends to be | | |
| 273 | -| | done by closures associated with | | |
| 274 | -| | the original request object (at | | |
| 275 | -| | least in JavaScript code). In | | |
| 276 | -| | languages without closures it | | |
| 277 | -| | might have some use. It may be | | |
| 278 | -| | any legal JSON value - it need | | |
| 279 | -| | not be confined to a string or | | |
| 280 | -| | number. | | |
| 281 | -+-----------------------------------+-----------------------------------+ | |
| 282 | -| resultCode | Standardized result code string | | |
| 283 | -| | in the form FOSSIL-\#\#\#\#.\ | | |
| 284 | -| | *Only error responses* contain a | | |
| 285 | -| | resultCode. | | |
| 286 | -+-----------------------------------+-----------------------------------+ | |
| 287 | -| resultText | *Possibly* a descriptive string, | | |
| 288 | -| | possibly empty. Supplements the | | |
| 289 | -| | resultCode, but can also be set | | |
| 290 | -| | on success responses (but | | |
| 291 | -| | normally isn't). Clients must not | | |
| 292 | -| | rely on any specific values being | | |
| 293 | -| | set here. | | |
| 294 | -+-----------------------------------+-----------------------------------+ | |
| 295 | -| payload | Request-specific response payload | | |
| 296 | -| | (data type/structure is | | |
| 297 | -| | request-specific). | | |
| 298 | -| | | | |
| 299 | -| | The payload is *never* set for | | |
| 300 | -| | error responses, *only* for | | |
| 301 | -| | success responses (and only those | | |
| 302 | -| | which actually have a payload - | | |
| 303 | -| | not all do). | | |
| 304 | -+-----------------------------------+-----------------------------------+ | |
| 305 | -| timestamp | Response timestamp (GMT Unix | | |
| 306 | -| | Epoch). We use seconds precision | | |
| 307 | -| | because i did not know at the | | |
| 308 | -| | time that Fossil actually records | | |
| 309 | -| | millisecond precision. | | |
| 310 | -+-----------------------------------+-----------------------------------+ | |
| 311 | -| payloadVersion | Not initially needed, but | | |
| 312 | -| | reserved for future use in | | |
| 313 | -| | maintaining version compatibility | | |
| 314 | -| | when the format of a given | | |
| 315 | -| | response type's payload changes. | | |
| 316 | -| | If needed, the "first version" | | |
| 317 | -| | value is assumed to be 0, for | | |
| 318 | -| | semantic \[near-\]compatibility | | |
| 319 | -| | with the undefined value clients | | |
| 320 | -| | see when this property is not | | |
| 321 | -| | set. | | |
| 322 | -+-----------------------------------+-----------------------------------+ | |
| 323 | -| command | Normalized form of the command | | |
| 324 | -| | being run. It consists of the | | |
| 325 | -| | "command" (non-argument) parts of | | |
| 326 | -| | the request path (or CLI | | |
| 327 | -| | positional arguments), excluding | | |
| 328 | -| | the initial "/json/" part. e.g. | | |
| 329 | -| | the "command" part of | | |
| 330 | -| | "/json/timeline/checkin?a=b" | | |
| 331 | -| | (CLI: json timeline checkin...) | | |
| 332 | -| | is "timeline/checkin" (both in | | |
| 333 | -| | CLI and HTTP modes). | | |
| 334 | -+-----------------------------------+-----------------------------------+ | |
| 335 | -| apiVersion | Not yet used, but reserved for a | | |
| 336 | -| | numeric value which represents | | |
| 337 | -| | the JSON API's version (which can | | |
| 338 | -| | be used to determine if it has a | | |
| 339 | -| | given feature or not). This will | | |
| 340 | -| | not be implemented until it's | | |
| 341 | -| | needed. | | |
| 342 | -+-----------------------------------+-----------------------------------+ | |
| 343 | -| warnings | Reserved for future use as a | | |
| 344 | -| | standard place to put non-fatal | | |
| 345 | -| | warnings in responses. Will be an | | |
| 346 | -| | array but the warning | | |
| 347 | -| | structure/type is not yet | | |
| 348 | -| | specified. Intended primarily as | | |
| 349 | -| | a debugging tool, and will | | |
| 350 | -| | "probably not" become part of the | | |
| 351 | -| | public client interface. | | |
| 352 | -+-----------------------------------+-----------------------------------+ | |
| 353 | -| g | Fossil administrators (those with | | |
| 354 | -| | the "a" or "s" permissions) may | | |
| 355 | -| | use the debugFossilG boolean | | |
| 356 | -| | request parameter (CLI: | | |
| 357 | -| | --json-debug-g) to enable this | | |
| 358 | -| | property for any given response. | | |
| 359 | -| | It contains a good deal of the | | |
| 360 | -| | server-side internal state at the | | |
| 361 | -| | time the response was generated, | | |
| 362 | -| | which is often useful in | | |
| 363 | -| | debuggering problems. Trivia: it | | |
| 364 | -| | is called "g" because that's the | | |
| 365 | -| | name of fossil's internal global | | |
| 366 | -| | state object. | | |
| 367 | -+-----------------------------------+-----------------------------------+ | |
| 368 | -| procTimeMs | For debugging only - generic | | |
| 369 | -| | clients must not rely on this | | |
| 370 | -| | property. Contains the number of | | |
| 371 | -| | milliseconds the JSON command | | |
| 372 | -| | processor needed to dispatch and | | |
| 373 | -| | process the command. TODO: move | | |
| 374 | -| | the timer into the fossil core so | | |
| 375 | -| | that we can generically time its | | |
| 376 | -| | responses and include the startup | | |
| 377 | -| | overhead in the time calculation. | | |
| 378 | -+-----------------------------------+-----------------------------------+ | |
| 379 | -``` | |
| 209 | + | |
| 210 | +- `fossil`: Fossil server version string. This property is basically | |
| 211 | + "the official response envelope marker" - if it is set, clients can | |
| 212 | + "probably safely assume" that the object indeed came from one of the | |
| 213 | + Fossil/JSON APIs. This API never creates responses which do not | |
| 214 | + contain this property. | |
| 215 | +- `requestId`: Only set if the request contained it, and then it is | |
| 216 | + echoed back to the caller as-is. This can be use to determine | |
| 217 | + (client-side) which request a given response is coming in for | |
| 218 | + (assuming multiple asynchronous requests are pending). In practice | |
| 219 | + this generally isn’t needed because response handling tends to be | |
| 220 | + done by closures associated with the original request object (at | |
| 221 | + least in JavaScript code). In languages without closures it might | |
| 222 | + have some use. It may be any legal JSON value - it need not be | |
| 223 | + confined to a string or number. | |
| 224 | +- `resultCode`: Standardized result code string in the form | |
| 225 | + `FOSSIL-####`. Only error responses contain a `resultCode`. | |
| 226 | +- `resultText`: Possibly a descriptive string, possibly | |
| 227 | + empty. Supplements the resultCode, but can also be set on success | |
| 228 | + responses (but normally isn't). Clients must not rely on any | |
| 229 | + specific values being set here. | |
| 230 | +- `payload`: Request-specific response payload (data type/structure is | |
| 231 | + request-specific). The payload is never set for error responses, | |
| 232 | + only for success responses (and only those which actually have a | |
| 233 | + payload - not all do). | |
| 234 | +- `timestamp`: Response timestamp (GMT Unix Epoch). We use seconds | |
| 235 | + precision because i did not know at the time that Fossil actually | |
| 236 | + records millisecond precision. | |
| 237 | +- `payloadVersion`: Not initially needed, but reserved for future use | |
| 238 | + in maintaining version compatibility when the format of a given | |
| 239 | + response type's payload changes. If needed, the "first version" | |
| 240 | + value is assumed to be 0, for semantic [near-]compatibility with the | |
| 241 | + undefined value clients see when this property is not set. | |
| 242 | +- `command`: Normalized form of the command being run. It consists of | |
| 243 | + the "command" (non-argument) parts of the request path (or CLI | |
| 244 | + positional arguments), excluding the initial "/json/" part. e.g. the | |
| 245 | + "command" part of "/json/timeline/checkin?a=b" (CLI: json timeline | |
| 246 | + checkin...) is "timeline/checkin" (both in CLI and HTTP modes). | |
| 247 | +- `apiVersion`: Not yet used, but reserved for a numeric value which | |
| 248 | + represents the JSON API's version (which can be used to determine if | |
| 249 | + it has a given feature or not). This will not be implemented until | |
| 250 | + it's needed. | |
| 251 | +- `warnings`: Reserved for future use as a standard place to put | |
| 252 | + non-fatal warnings in responses. Will be an array but the warning | |
| 253 | + structure/type is not yet specified. Intended primarily as a | |
| 254 | + debugging tool, and will "probably not" become part of the public | |
| 255 | + client interface. | |
| 256 | +- `g`: Fossil administrators (those with the "a" or "s" permissions) | |
| 257 | + may use the debugFossilG boolean request parameter (CLI: | |
| 258 | + --json-debug-g) to enable this property for any given response. It | |
| 259 | + contains a good deal of the server-side internal state at the time | |
| 260 | + the response was generated, which is often useful in debuggering | |
| 261 | + problems. Trivia: it is called "g" because that's the name of | |
| 262 | + fossil's internal global state object. | |
| 263 | +- `procTimeMs`: For debugging only - generic clients must not rely on | |
| 264 | + this property. Contains the number of milliseconds the JSON command | |
| 265 | + processor needed to dispatch and process the command. TODO: move the | |
| 266 | + timer into the fossil core so that we can generically time its | |
| 267 | + responses and include the startup overhead in the time calculation. | |
| 268 | + | |
| 269 | + | |
| 380 | 270 | |
| 381 | 271 | <a id="http-response-header"></a> |
| 382 | 272 | # HTTP Response Headers |
| 383 | 273 | |
| 384 | 274 | The Content-Type HTTP header of a response will be either |
| @@ -615,215 +505,115 @@ | ||
| 615 | 505 | [`src/json.c:json_err_cstr()`](/finfo/src/json.c). Changes there need |
| 616 | 506 | to be reflected here (and vice versa). Also, we have assertions in |
| 617 | 507 | place to ensure that C-side codes are in the range 1000-9999, so do |
| 618 | 508 | not just go blindly change the numeric ranges used by the enum. |
| 619 | 509 | |
| 620 | -TODO: convert to plain list: | |
| 621 | - | |
| 622 | -``` | |
| 623 | -+-----------------------------------+-----------------------------------+ | |
| 624 | -| **FOSSIL-0###** | **Non-error Category** | | |
| 625 | -+-----------------------------------+-----------------------------------+ | |
| 626 | -| FOSSIL-0000 | Success/not an error. Succesful | | |
| 627 | -| | responses do not contain a | | |
| 628 | -| | resultCode, so clients should | | |
| 629 | -| | never see this. | | |
| 630 | -+-----------------------------------+-----------------------------------+ | |
| 631 | -| FOSSIL-0### | Reserved for *potential* future | | |
| 632 | -| | use in reporting non-fatal | | |
| 633 | -| | warnings. | | |
| 634 | -+-----------------------------------+-----------------------------------+ | |
| 635 | -| | | | |
| 636 | -+-----------------------------------+-----------------------------------+ | |
| 637 | -| **FOSSIL-1000** | **Generic Errors Category** | | |
| 638 | -+-----------------------------------+-----------------------------------+ | |
| 639 | -| FOSSIL-1101 | Invalid request. Request envelope | | |
| 640 | -| | is invalid or missing. | | |
| 641 | -+-----------------------------------+-----------------------------------+ | |
| 642 | -| FOSSIL-1102 | Unknown command. This is only | | |
| 643 | -| | useful if we dispatch all | | |
| 644 | -| | /json/XXX paths through a central | | |
| 645 | -| | dispatcher and the XXX part is an | | |
| 646 | -| | unknown command. | | |
| 647 | -+-----------------------------------+-----------------------------------+ | |
| 648 | -| FOSSIL-1103 | Unknown/unspecified error | | |
| 649 | -+-----------------------------------+-----------------------------------+ | |
| 650 | -| FOSSIL-1104 | RE-USE | | |
| 651 | -+-----------------------------------+-----------------------------------+ | |
| 652 | -| FOSSIL-1105 | A server-side timeout was | | |
| 653 | -| | reached. (i’m not sure we can | | |
| 654 | -| | actually implement this one, | | |
| 655 | -| | though.) | | |
| 656 | -+-----------------------------------+-----------------------------------+ | |
| 657 | -| FOSSIL-1106 | Assertion failed (or would have | | |
| 658 | -| | had we continued). Note: if an | | |
| 659 | -| | assert() fails in CGI/server | | |
| 660 | -| | modes, the HTTP response will be | | |
| 661 | -| | code 500 (Internal Server Error). | | |
| 662 | -| | We want to avoid that and return | | |
| 663 | -| | a JSON response instead. | | |
| 664 | -| | | | |
| 665 | -| | All of that said - i have no real | | |
| 666 | -| | intention of implementing this, | | |
| 667 | -| | since assertions are "truly | | |
| 668 | -| | serious" errors. | | |
| 669 | -+-----------------------------------+-----------------------------------+ | |
| 670 | -| FOSSIL-1107 | Allocation/out of memory error.\ | | |
| 671 | -| | There is a way to report this via | | |
| 672 | -| | JSON without allocating further | | |
| 673 | -| | memory. Well, depending on where | | |
| 674 | -| | exactly it happens. That said, | | |
| 675 | -| | much of the code does not check | | |
| 676 | -| | this condition or asserts() if an | | |
| 677 | -| | alloc fails. | | |
| 678 | -| | | | |
| 679 | -| | Fossil's internal allocator | | |
| 680 | -| | abort()s on OOM, so we can't | | |
| 681 | -| | actually implement this, only | | |
| 682 | -| | reserve it for use with, e.g., | | |
| 683 | -| | libfossil. | | |
| 684 | -+-----------------------------------+-----------------------------------+ | |
| 685 | -| FOSSIL-1108 | Requested API is not yet | | |
| 686 | -| | implemented. | | |
| 687 | -+-----------------------------------+-----------------------------------+ | |
| 688 | -| FOSSIL-1109 | Panic! Fossil's `fossil_panic()` | | |
| 689 | -| | or `cgi_panic()`was called. In | | |
| 690 | -| | non-JSON HTML mode this produces | | |
| 691 | -| | an HTTP 500 error. Clients | | |
| 692 | -| | "should" report this as a | | |
| 693 | -| | potential bug, as it "possibly" | | |
| 694 | -| | indicates that the C code has | | |
| 695 | -| | incorrect argument- or error | | |
| 696 | -| | handling somewhere. | | |
| 697 | -+-----------------------------------+-----------------------------------+ | |
| 698 | -| FOSSIL-1110 | Reading of artifact manifest | | |
| 699 | -| | failed. Time to contact your | | |
| 700 | -| | local fossil guru. | | |
| 701 | -+-----------------------------------+-----------------------------------+ | |
| 702 | -| FOSSIL-1111 | Opening of file failed (e.g. POST | | |
| 703 | -| | data provided to CLI mode). | | |
| 704 | -+-----------------------------------+-----------------------------------+ | |
| 705 | -| | | | |
| 706 | -+-----------------------------------+-----------------------------------+ | |
| 707 | -| **FOSSIL-2000** | **Authentication/Access Error | | |
| 708 | -| | Category** | | |
| 709 | -+-----------------------------------+-----------------------------------+ | |
| 710 | -| FOSSIL-2001 | Privileged request was missing | | |
| 711 | -| | authentication token/cookie. | | |
| 712 | -+-----------------------------------+-----------------------------------+ | |
| 713 | -| FOSSIL-2002 | Access to requested resource was | | |
| 714 | -| | denied. Oftentimes the resultText | | |
| 715 | -| | property will contain a | | |
| 716 | -| | human-language description of the | | |
| 717 | -| | access rights needed for the | | |
| 718 | -| | given command. | | |
| 719 | -+-----------------------------------+-----------------------------------+ | |
| 720 | -| FOSSIL-2003 | Requested command is not | | |
| 721 | -| | available in the current | | |
| 722 | -| | operating mode. Returned in CLI | | |
| 723 | -| | mode by commands which require | | |
| 724 | -| | HTTP mode (e.g. login), and vice | | |
| 725 | -| | versa. | | |
| 726 | -+-----------------------------------+-----------------------------------+ | |
| 727 | -| | | | |
| 728 | -+-----------------------------------+-----------------------------------+ | |
| 729 | -| FOSSIL-2100 | Login Failed. | | |
| 730 | -+-----------------------------------+-----------------------------------+ | |
| 731 | -| FOSSIL-2101 | Anonymous login attempt is | | |
| 732 | -| | missing the "anonymousSeed" | | |
| 733 | -| | property (fetched via the | | |
| 734 | -| | /json/anonymousPassword request). | | |
| 735 | -| | Note that this is more specific | | |
| 736 | -| | form of FOSSIL-3002. | | |
| 737 | -+-----------------------------------+-----------------------------------+ | |
| 738 | -| | **ONLY FOR TESTING purposes | | |
| 739 | -| | should the remaning 210X | | |
| 740 | -| | sub-codes be enabled (they are | | |
| 741 | -| | potentially security-relevant, in | | |
| 742 | -| | that the client knows which part | | |
| 743 | -| | of the request was | | |
| 744 | -| | valid/invalid)** | | |
| 745 | -+-----------------------------------+-----------------------------------+ | |
| 746 | -| FOSSIL-2102 | Name not supplied in login | | |
| 747 | -| | request | | |
| 748 | -+-----------------------------------+-----------------------------------+ | |
| 749 | -| FOSSIL-2103 | Password not supplied in login | | |
| 750 | -| | request | | |
| 751 | -+-----------------------------------+-----------------------------------+ | |
| 752 | -| FOSSIL-2104 | No name/password match found | | |
| 753 | -+-----------------------------------+-----------------------------------+ | |
| 754 | -| | | | |
| 755 | -+-----------------------------------+-----------------------------------+ | |
| 756 | -| **FOSSIL-3000** | **Usage Error Category** | | |
| 757 | -+-----------------------------------+-----------------------------------+ | |
| 758 | -| FOSSIL-3001 | Invalid argument/parameter | | |
| 759 | -| | type(s) or value(s) in request | | |
| 760 | -+-----------------------------------+-----------------------------------+ | |
| 761 | -| FOSSIL-3002 | Required argument(s)/parameter(s) | | |
| 762 | -| | missing from request | | |
| 763 | -+-----------------------------------+-----------------------------------+ | |
| 764 | -| FOSSIL-3003 | Requested resource identifier is | | |
| 765 | -| | ambiguous (e.g. a shortened UUID | | |
| 766 | -| | can be ambiguous). | | |
| 767 | -+-----------------------------------+-----------------------------------+ | |
| 768 | -| FOSSIL-3004 | Unresolved resource identifier. A | | |
| 769 | -| | branch/tag/uuid provided by | | |
| 770 | -| | client code could not be | | |
| 771 | -| | resolved.\ | | |
| 772 | -| | This is a special case of #3006. | | |
| 773 | -+-----------------------------------+-----------------------------------+ | |
| 774 | -| FOSSIL-3005 | Resource already exists and | | |
| 775 | -| | overwriting/replacing is not | | |
| 776 | -| | allowed. e.g. trying to create a | | |
| 777 | -| | wiki page or user which already | | |
| 778 | -| | exists. | | |
| 779 | -| | | | |
| 780 | -| | FIXME? Consolidate this and | | |
| 781 | -| | resource-not-found into a | | |
| 782 | -| | separate category for dumb-down | | |
| 783 | -| | purposes? | | |
| 784 | -+-----------------------------------+-----------------------------------+ | |
| 785 | -| FOSSIL-3006 | Requested resource not found. e.g | | |
| 786 | -| | artifact ID, branch name, etc. | | |
| 787 | -+-----------------------------------+-----------------------------------+ | |
| 788 | -| | | | |
| 789 | -+-----------------------------------+-----------------------------------+ | |
| 790 | -| **FOSSIL-4000** | **Database-related Error | | |
| 791 | -| | Category** | | |
| 792 | -+-----------------------------------+-----------------------------------+ | |
| 793 | -| FOSSIL-4001 | Statement preparation failed. | | |
| 794 | -+-----------------------------------+-----------------------------------+ | |
| 795 | -| FOSSIL-4002 | Parameter binding failed. | | |
| 796 | -+-----------------------------------+-----------------------------------+ | |
| 797 | -| FOSSIL-4003 | Statement execution failed. | | |
| 798 | -+-----------------------------------+-----------------------------------+ | |
| 799 | -| FOSSIL-4004 | Database locked (this is not used | | |
| 800 | -| | anywhere, but reserved for future | | |
| 801 | -| | use). | | |
| 802 | -+-----------------------------------+-----------------------------------+ | |
| 803 | -| | **Special-case DB-related | | |
| 804 | -| | errors...** | | |
| 805 | -+-----------------------------------+-----------------------------------+ | |
| 806 | -| FOSSIL-4101 | Fossil Schema out of date (repo | | |
| 807 | -| | rebuild required). | | |
| 808 | -+-----------------------------------+-----------------------------------+ | |
| 809 | -| FOSSIL-4102 | Fossil repo db could not be | | |
| 810 | -| | found. | | |
| 811 | -+-----------------------------------+-----------------------------------+ | |
| 812 | -| FOSSIL-4103 | Repository db is not valid | | |
| 813 | -| | (possibly corrupt). | | |
| 814 | -+-----------------------------------+-----------------------------------+ | |
| 815 | -| FOSSIL-4104 | Check-out not found. This is | | |
| 816 | -| | similar to FOSSIL-4102 but | | |
| 817 | -| | indicates that a local checkout | | |
| 818 | -| | is required (but was not found). | | |
| 819 | -| | Note that the 4102 gets triggered | | |
| 820 | -| | earlier than this one, and so can | | |
| 821 | -| | appear in cases when a user might | | |
| 822 | -| | otherwise expect a 4104 error. | | |
| 823 | -+-----------------------------------+-----------------------------------+ | |
| 824 | -``` | |
| 510 | + | |
| 511 | +**`FOSSIL-0###`: Non-error Category** | |
| 512 | + | |
| 513 | +- `FOSSIL-0000`: Success/not an error. Succesful responses do not | |
| 514 | + contain a resultCode, so clients should never see this. | |
| 515 | +- `FOSSIL-0###`: Reserved for potential future use in reporting | |
| 516 | + non-fatal warnings. | |
| 517 | + | |
| 518 | + | |
| 519 | + | |
| 520 | +**`FOSSIL-1000`: Generic Errors Category** | |
| 521 | + | |
| 522 | +- `FOSSIL-1101`: Invalid request. Request envelope is invalid or | |
| 523 | + missing. | |
| 524 | +- `FOSSIL-1102`: Unknown JSON command. | |
| 525 | +- `FOSSIL-1103`: Unknown/unspecified error | |
| 526 | +- `FOSSIL-1104`: RE-USE | |
| 527 | +- `FOSSIL-1105`: A server-side timeout was reached. (i’m not sure we | |
| 528 | + can actually implement this one, though.) | |
| 529 | +- `FOSSIL-1106`: Assertion failed (or would have had we | |
| 530 | + continued). Note: if an `assert()` fails in CGI/server modes, the HTTP | |
| 531 | + response will be code 500 (Internal Server Error). We want to avoid | |
| 532 | + that and return a JSON response instead. All of that said - there seems | |
| 533 | + to be little reason to implementi this, since assertions are "truly | |
| 534 | + serious" errors. | |
| 535 | +- `FOSSIL-1107`: Allocation/out of memory error. This cannot be reasonably | |
| 536 | + reported because fossil aborts if an allocation fails. | |
| 537 | +- `FOSSIL-1108`: Requested API is not yet implemented. | |
| 538 | +- `FOSSIL-1109`: Panic! Fossil's `fossil_panic()` or `cgi_panic()` was | |
| 539 | + called. In non-JSON HTML mode this produces an HTTP 500 | |
| 540 | + error. Clients "should" report this as a potential bug, as it | |
| 541 | + "possibly" indicates that the C code has incorrect argument- or | |
| 542 | + error handling somewhere. | |
| 543 | +- `FOSSIL-1110`: Reading of artifact manifest failed. Time to contact | |
| 544 | + your local fossil guru. | |
| 545 | +- `FOSSIL-1111`: Opening of file failed (e.g. POST data provided to | |
| 546 | + CLI mode). | |
| 547 | + | |
| 548 | + | |
| 549 | +**`FOSSIL-2000`: Authentication/Access Error Category** | |
| 550 | + | |
| 551 | +- `FOSSIL-2001`: Privileged request was missing authentication | |
| 552 | + token/cookie. | |
| 553 | +- `FOSSIL-2002`: Access to requested resource was denied. Oftentimes | |
| 554 | + the `resultText` property will contain a human-language description of | |
| 555 | + the access rights needed for the given command. | |
| 556 | +- `FOSSIL-2003`: Requested command is not available in the current | |
| 557 | + operating mode. Returned in CLI mode by commands which require HTTP | |
| 558 | + mode (e.g. login), and vice versa. FIXME: now that we can simulate | |
| 559 | + POST in CLI mode, we can get rid of this distinction for some of the | |
| 560 | + commands. | |
| 561 | +- `FOSSIL-2100`: Login Failed. | |
| 562 | +- `FOSSIL-2101`: Anonymous login attempt is missing the | |
| 563 | + "anonymousSeed" property (fetched via [the `/json/anonymousPassword` | |
| 564 | + request](api-auth.md#login-anonymous)). Note that this is more | |
| 565 | + specific form of `FOSSIL-3002`. | |
| 566 | + | |
| 567 | + | |
| 568 | +ONLY FOR TESTING purposes should the remaning 210X sub-codes be | |
| 569 | +enabled (they are potentially security-relevant, in that the client | |
| 570 | +knows which part of the request was valid/invalid): | |
| 571 | + | |
| 572 | +- `FOSSIL-2102`: Name not supplied in login request | |
| 573 | +- `FOSSIL-2103`: Password not supplied in login request | |
| 574 | +- `FOSSIL-2104`: No name/password match found | |
| 575 | + | |
| 576 | + | |
| 577 | +**`FOSSIL-3000`: Usage Error Category** | |
| 578 | + | |
| 579 | +- `FOSSIL-3001`: Invalid argument/parameter type(s) or value(s) in | |
| 580 | + request | |
| 581 | +- `FOSSIL-3002`: Required argument(s)/parameter(s) missing from | |
| 582 | + request | |
| 583 | +- `FOSSIL-3003`: Requested resource identifier is ambiguous (e.g. a | |
| 584 | + shortened UUID can be ambiguous). | |
| 585 | +- `FOSSIL-3004`: Unresolved resource identifier. A branch/tag/uuid | |
| 586 | + provided by client code could not be resolved. This is a special | |
| 587 | + case of #3006. | |
| 588 | +- `FOSSIL-3005`: Resource already exists and overwriting/replacing is | |
| 589 | + not allowed. e.g. trying to create a wiki page or user which already | |
| 590 | + exists. FIXME? Consolidate this and resource-not-found into a | |
| 591 | + separate category for dumb-down purposes? | |
| 592 | +- `FOSSIL-3006`: Requested resource not found. e.g artifact ID, branch | |
| 593 | + name, etc. | |
| 594 | + | |
| 595 | + | |
| 596 | +**`FOSSIL-4000`: Database-related Error Category** | |
| 597 | + | |
| 598 | +- `FOSSIL-4001`: Statement preparation failed. | |
| 599 | +- `FOSSIL-4002`: Parameter binding failed. | |
| 600 | +- `FOSSIL-4003`: Statement execution failed. | |
| 601 | +- `FOSSIL-4004`: Database locked (this is not used anywhere, but | |
| 602 | + reserved for future use). | |
| 603 | + | |
| 604 | +Special-case DB-related errors... | |
| 605 | + | |
| 606 | +- `FOSSIL-4101`: Fossil Schema out of date (repo rebuild required). | |
| 607 | +- `FOSSIL-4102`: Fossil repo db could not be found. | |
| 608 | +- `FOSSIL-4103`: Repository db is not valid (possibly corrupt). | |
| 609 | +- `FOSSIL-4104`: Check-out not found. This is similar to FOSSIL-4102 | |
| 610 | + but indicates that a local checkout is required (but was not | |
| 611 | + found). Note that the 4102 gets triggered earlier than this one, and | |
| 612 | + so can appear in cases when a user might otherwise expect a 4104 | |
| 613 | + error. | |
| 614 | + | |
| 825 | 615 | |
| 826 | 616 | Some of those error codes are of course "too detailed" for the client to |
| 827 | 617 | do anything with (e.g.. 4001-4004), but their intention is to make it |
| 828 | 618 | easier for Fossil developers to (A) track down problems and (B) support |
| 829 | 619 | clients who report problems. If a client reports, "I get a FOSSIL-4000, |
| 830 | 620 |
| --- www/json-api/conventions.md | |
| +++ www/json-api/conventions.md | |
| @@ -3,11 +3,12 @@ | |
| 3 | |
| 4 | Jump to: |
| 5 | |
| 6 | * [JSON Property Naming](#property-names) |
| 7 | * [HTTP GET Requests](#http-get) |
| 8 | * [HTTP Post Requests](#http-post) |
| 9 | * [Request Parameter Data Types](#request-param-types) |
| 10 | * [Response Envelope](#response-envelope) |
| 11 | * [HTTP Response Headers](#http-response-header) |
| 12 | * [CLI vs. HTTP Mode](#cli-vs-http) |
| 13 | * [Simulating POSTed data](#simulating-post-data) |
| @@ -27,22 +28,23 @@ | |
| 27 | |
| 28 | <a id="http-get"></a> |
| 29 | # HTTP GET Requests |
| 30 | |
| 31 | Many (if not most) requests can be made via simple GET requests, e.g. we |
| 32 | *could* use any of the following: |
| 33 | |
| 34 | - `http://..../timeline/json` |
| 35 | - `/timeline?format=json` |
| 36 | - `/timeline?json=1` |
| 37 | - `/timeline.json` |
| 38 | - `/json/timeline?...options...` |
| 39 | |
| 40 | After several discussions, the API settled on the `/json/...` convention, |
| 41 | primarily because it simplifies dispatching and argument-handling logic |
| 42 | compared to the `/[.../]foo.json` approach. Using `/json/...` allows us |
| 43 | to unify that logic for all JSON sub-commands, for both CLI and HTTP modes. |
| 44 | |
| 45 | <a id="http-post"></a> |
| 46 | # HTTP Post Requests |
| 47 | |
| 48 | Certain requests, mainly things like editing checkin messages and |
| @@ -56,86 +58,42 @@ | |
| 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, | |
| 65 | | | not used by fossil, but returned | |
| 66 | | | as-is in responses. | |
| 67 | +-----------------------------------+-----------------------------------+ |
| 68 | | command | Provides a secondary mechanism | |
| 69 | | | for specifying which JSON command | |
| 70 | | | should be run. A request path of | |
| 71 | | | /json/foo/bar is equivalent to a | |
| 72 | | | request with path=/json and | |
| 73 | | | command=foo/bar. Note that | |
| 74 | | | subpaths do *not* work this way. | |
| 75 | | | e.g. path=/json/foo, command=bar | |
| 76 | | | will not work, but path=/json, | |
| 77 | | | command=foo/bar will. | |
| 78 | | | | |
| 79 | | | This option is particularly | |
| 80 | | | useful when generating JSON for | |
| 81 | | | piping in to CLI mode, but it | |
| 82 | | | also has some | |
| 83 | | | response-dispatching uses on the | |
| 84 | | | client side. | |
| 85 | +-----------------------------------+-----------------------------------+ |
| 86 | | authToken | Authentication token. Created by | |
| 87 | | | a login request. Determines what | |
| 88 | | | access rights the user has, and | |
| 89 | | | any given request may require | |
| 90 | | | specific rights. In principle | |
| 91 | | | this is required by any request | |
| 92 | | | which needs non-guest privileges, | |
| 93 | | | but cookie-aware clients do not | |
| 94 | | | manually need to track this (it | |
| 95 | | | is managed as a cookie by the | |
| 96 | | | agent/browser). | |
| 97 | +-----------------------------------+-----------------------------------+ |
| 98 | | payload | Command-specific parameters. Most | |
| 99 | | | can optionally come in via GET | |
| 100 | | | parameters, but those taking | |
| 101 | | | complex structures expect them to | |
| 102 | | | be placed here. | |
| 103 | +-----------------------------------+-----------------------------------+ |
| 104 | | indent | Optionally specifies indentation | |
| 105 | | | for the output. 0=no indention. | |
| 106 | | | 1=a single TAB character for each | |
| 107 | | | level of indentation. >1 means | |
| 108 | | | that many *spaces* per level. | |
| 109 | | | e.g. indent=7 means to indent 7 | |
| 110 | | | spaces per object/array depth | |
| 111 | | | level. cson also supports other | |
| 112 | | | flags for fine-tuning the output | |
| 113 | | | spacing, and adding them to this | |
| 114 | | | interface might be interesting at | |
| 115 | | | some point. e.g. whether or not | |
| 116 | | | to add a newline to the output.\ | |
| 117 | | | CLI mode adds extra indentation | |
| 118 | | | by default, whereas CGI/server | |
| 119 | | | modes produce unindented output | |
| 120 | | | by default. | |
| 121 | +-----------------------------------+-----------------------------------+ |
| 122 | | jsonp | Optional String (client function | |
| 123 | | | name). | |
| 124 | | | | |
| 125 | | | Requests which include this will | |
| 126 | | | be returned with Content-Type | |
| 127 | | | application/javascript and will | |
| 128 | | | be wrapped up in a function call | |
| 129 | | | using the given name. e.g. if | |
| 130 | | | jsonp=foo then the result would | |
| 131 | | | look like: | |
| 132 | | | | |
| 133 | | | foo( {...the response | |
| 134 | | | envelope...} ) | |
| 135 | +-----------------------------------+-----------------------------------+ |
| 136 | ``` |
| 137 | |
| 138 | The API allows most of those (normally all but the payload) to come in |
| 139 | as either GET parameters or properties of the top-level POSTed request |
| 140 | JSON envelope, with GET taking priority over POST. (Reminder to self: we |
| 141 | could potentially also use values from cookies. Fossil currently only |
| @@ -180,16 +138,17 @@ | |
| 180 | } |
| 181 | } |
| 182 | ``` |
| 183 | |
| 184 | When a given parameter is set in two places, e.g. GET and POST, or |
| 185 | POST-from-a-file and CLI parameters, which one takes precedence depends |
| 186 | on the concrete command handler (and may be unspecified). Most will give |
| 187 | precedence to CLI and GET parameters, but POSTed values are technically |
| 188 | preferred for non-string data because no additional "type guessing" or |
| 189 | string-to-whatever conversion has to be made (GET/CLI parameters are |
| 190 | *always* strings, even if they look like a number or boolean). |
| 191 | |
| 192 | |
| 193 | <a id="request-param-types"></a> |
| 194 | # Request Parameter Data Types |
| 195 | |
| @@ -245,140 +204,71 @@ | |
| 245 | |
| 246 | Every response comes in the form of a HTTP response or (in CLI mode) |
| 247 | JSON sent to stdout. The body of the response is a JSON object following |
| 248 | a common envelope format. The envelope has the following properties: |
| 249 | |
| 250 | (TODO: convert to a simple list...) |
| 251 | ``` |
| 252 | +-----------------------------------+-----------------------------------+ |
| 253 | | fossil | Fossil server version string. | |
| 254 | | | This property is basically "the | |
| 255 | | | official response envelope | |
| 256 | | | marker" - if it is set, clients | |
| 257 | | | can "probably safely assume" that | |
| 258 | | | the object indeed came from one | |
| 259 | | | of the Fossil/JSON APIs. This API | |
| 260 | | | never creates responses which do | |
| 261 | | | not contain this property. | |
| 262 | +-----------------------------------+-----------------------------------+ |
| 263 | | requestId | Only set if the request contained | |
| 264 | | | it, and then it is echoed back to | |
| 265 | | | the caller as-is. This can be use | |
| 266 | | | to determine (client-side) which | |
| 267 | | | request a given response is | |
| 268 | | | coming in for (assuming multiple | |
| 269 | | | asynchronous requests are | |
| 270 | | | pending). In practice this | |
| 271 | | | generally isn’t needed because | |
| 272 | | | response handling tends to be | |
| 273 | | | done by closures associated with | |
| 274 | | | the original request object (at | |
| 275 | | | least in JavaScript code). In | |
| 276 | | | languages without closures it | |
| 277 | | | might have some use. It may be | |
| 278 | | | any legal JSON value - it need | |
| 279 | | | not be confined to a string or | |
| 280 | | | number. | |
| 281 | +-----------------------------------+-----------------------------------+ |
| 282 | | resultCode | Standardized result code string | |
| 283 | | | in the form FOSSIL-\#\#\#\#.\ | |
| 284 | | | *Only error responses* contain a | |
| 285 | | | resultCode. | |
| 286 | +-----------------------------------+-----------------------------------+ |
| 287 | | resultText | *Possibly* a descriptive string, | |
| 288 | | | possibly empty. Supplements the | |
| 289 | | | resultCode, but can also be set | |
| 290 | | | on success responses (but | |
| 291 | | | normally isn't). Clients must not | |
| 292 | | | rely on any specific values being | |
| 293 | | | set here. | |
| 294 | +-----------------------------------+-----------------------------------+ |
| 295 | | payload | Request-specific response payload | |
| 296 | | | (data type/structure is | |
| 297 | | | request-specific). | |
| 298 | | | | |
| 299 | | | The payload is *never* set for | |
| 300 | | | error responses, *only* for | |
| 301 | | | success responses (and only those | |
| 302 | | | which actually have a payload - | |
| 303 | | | not all do). | |
| 304 | +-----------------------------------+-----------------------------------+ |
| 305 | | timestamp | Response timestamp (GMT Unix | |
| 306 | | | Epoch). We use seconds precision | |
| 307 | | | because i did not know at the | |
| 308 | | | time that Fossil actually records | |
| 309 | | | millisecond precision. | |
| 310 | +-----------------------------------+-----------------------------------+ |
| 311 | | payloadVersion | Not initially needed, but | |
| 312 | | | reserved for future use in | |
| 313 | | | maintaining version compatibility | |
| 314 | | | when the format of a given | |
| 315 | | | response type's payload changes. | |
| 316 | | | If needed, the "first version" | |
| 317 | | | value is assumed to be 0, for | |
| 318 | | | semantic \[near-\]compatibility | |
| 319 | | | with the undefined value clients | |
| 320 | | | see when this property is not | |
| 321 | | | set. | |
| 322 | +-----------------------------------+-----------------------------------+ |
| 323 | | command | Normalized form of the command | |
| 324 | | | being run. It consists of the | |
| 325 | | | "command" (non-argument) parts of | |
| 326 | | | the request path (or CLI | |
| 327 | | | positional arguments), excluding | |
| 328 | | | the initial "/json/" part. e.g. | |
| 329 | | | the "command" part of | |
| 330 | | | "/json/timeline/checkin?a=b" | |
| 331 | | | (CLI: json timeline checkin...) | |
| 332 | | | is "timeline/checkin" (both in | |
| 333 | | | CLI and HTTP modes). | |
| 334 | +-----------------------------------+-----------------------------------+ |
| 335 | | apiVersion | Not yet used, but reserved for a | |
| 336 | | | numeric value which represents | |
| 337 | | | the JSON API's version (which can | |
| 338 | | | be used to determine if it has a | |
| 339 | | | given feature or not). This will | |
| 340 | | | not be implemented until it's | |
| 341 | | | needed. | |
| 342 | +-----------------------------------+-----------------------------------+ |
| 343 | | warnings | Reserved for future use as a | |
| 344 | | | standard place to put non-fatal | |
| 345 | | | warnings in responses. Will be an | |
| 346 | | | array but the warning | |
| 347 | | | structure/type is not yet | |
| 348 | | | specified. Intended primarily as | |
| 349 | | | a debugging tool, and will | |
| 350 | | | "probably not" become part of the | |
| 351 | | | public client interface. | |
| 352 | +-----------------------------------+-----------------------------------+ |
| 353 | | g | Fossil administrators (those with | |
| 354 | | | the "a" or "s" permissions) may | |
| 355 | | | use the debugFossilG boolean | |
| 356 | | | request parameter (CLI: | |
| 357 | | | --json-debug-g) to enable this | |
| 358 | | | property for any given response. | |
| 359 | | | It contains a good deal of the | |
| 360 | | | server-side internal state at the | |
| 361 | | | time the response was generated, | |
| 362 | | | which is often useful in | |
| 363 | | | debuggering problems. Trivia: it | |
| 364 | | | is called "g" because that's the | |
| 365 | | | name of fossil's internal global | |
| 366 | | | state object. | |
| 367 | +-----------------------------------+-----------------------------------+ |
| 368 | | procTimeMs | For debugging only - generic | |
| 369 | | | clients must not rely on this | |
| 370 | | | property. Contains the number of | |
| 371 | | | milliseconds the JSON command | |
| 372 | | | processor needed to dispatch and | |
| 373 | | | process the command. TODO: move | |
| 374 | | | the timer into the fossil core so | |
| 375 | | | that we can generically time its | |
| 376 | | | responses and include the startup | |
| 377 | | | overhead in the time calculation. | |
| 378 | +-----------------------------------+-----------------------------------+ |
| 379 | ``` |
| 380 | |
| 381 | <a id="http-response-header"></a> |
| 382 | # HTTP Response Headers |
| 383 | |
| 384 | The Content-Type HTTP header of a response will be either |
| @@ -615,215 +505,115 @@ | |
| 615 | [`src/json.c:json_err_cstr()`](/finfo/src/json.c). Changes there need |
| 616 | to be reflected here (and vice versa). Also, we have assertions in |
| 617 | place to ensure that C-side codes are in the range 1000-9999, so do |
| 618 | not just go blindly change the numeric ranges used by the enum. |
| 619 | |
| 620 | TODO: convert to plain list: |
| 621 | |
| 622 | ``` |
| 623 | +-----------------------------------+-----------------------------------+ |
| 624 | | **FOSSIL-0###** | **Non-error Category** | |
| 625 | +-----------------------------------+-----------------------------------+ |
| 626 | | FOSSIL-0000 | Success/not an error. Succesful | |
| 627 | | | responses do not contain a | |
| 628 | | | resultCode, so clients should | |
| 629 | | | never see this. | |
| 630 | +-----------------------------------+-----------------------------------+ |
| 631 | | FOSSIL-0### | Reserved for *potential* future | |
| 632 | | | use in reporting non-fatal | |
| 633 | | | warnings. | |
| 634 | +-----------------------------------+-----------------------------------+ |
| 635 | | | | |
| 636 | +-----------------------------------+-----------------------------------+ |
| 637 | | **FOSSIL-1000** | **Generic Errors Category** | |
| 638 | +-----------------------------------+-----------------------------------+ |
| 639 | | FOSSIL-1101 | Invalid request. Request envelope | |
| 640 | | | is invalid or missing. | |
| 641 | +-----------------------------------+-----------------------------------+ |
| 642 | | FOSSIL-1102 | Unknown command. This is only | |
| 643 | | | useful if we dispatch all | |
| 644 | | | /json/XXX paths through a central | |
| 645 | | | dispatcher and the XXX part is an | |
| 646 | | | unknown command. | |
| 647 | +-----------------------------------+-----------------------------------+ |
| 648 | | FOSSIL-1103 | Unknown/unspecified error | |
| 649 | +-----------------------------------+-----------------------------------+ |
| 650 | | FOSSIL-1104 | RE-USE | |
| 651 | +-----------------------------------+-----------------------------------+ |
| 652 | | FOSSIL-1105 | A server-side timeout was | |
| 653 | | | reached. (i’m not sure we can | |
| 654 | | | actually implement this one, | |
| 655 | | | though.) | |
| 656 | +-----------------------------------+-----------------------------------+ |
| 657 | | FOSSIL-1106 | Assertion failed (or would have | |
| 658 | | | had we continued). Note: if an | |
| 659 | | | assert() fails in CGI/server | |
| 660 | | | modes, the HTTP response will be | |
| 661 | | | code 500 (Internal Server Error). | |
| 662 | | | We want to avoid that and return | |
| 663 | | | a JSON response instead. | |
| 664 | | | | |
| 665 | | | All of that said - i have no real | |
| 666 | | | intention of implementing this, | |
| 667 | | | since assertions are "truly | |
| 668 | | | serious" errors. | |
| 669 | +-----------------------------------+-----------------------------------+ |
| 670 | | FOSSIL-1107 | Allocation/out of memory error.\ | |
| 671 | | | There is a way to report this via | |
| 672 | | | JSON without allocating further | |
| 673 | | | memory. Well, depending on where | |
| 674 | | | exactly it happens. That said, | |
| 675 | | | much of the code does not check | |
| 676 | | | this condition or asserts() if an | |
| 677 | | | alloc fails. | |
| 678 | | | | |
| 679 | | | Fossil's internal allocator | |
| 680 | | | abort()s on OOM, so we can't | |
| 681 | | | actually implement this, only | |
| 682 | | | reserve it for use with, e.g., | |
| 683 | | | libfossil. | |
| 684 | +-----------------------------------+-----------------------------------+ |
| 685 | | FOSSIL-1108 | Requested API is not yet | |
| 686 | | | implemented. | |
| 687 | +-----------------------------------+-----------------------------------+ |
| 688 | | FOSSIL-1109 | Panic! Fossil's `fossil_panic()` | |
| 689 | | | or `cgi_panic()`was called. In | |
| 690 | | | non-JSON HTML mode this produces | |
| 691 | | | an HTTP 500 error. Clients | |
| 692 | | | "should" report this as a | |
| 693 | | | potential bug, as it "possibly" | |
| 694 | | | indicates that the C code has | |
| 695 | | | incorrect argument- or error | |
| 696 | | | handling somewhere. | |
| 697 | +-----------------------------------+-----------------------------------+ |
| 698 | | FOSSIL-1110 | Reading of artifact manifest | |
| 699 | | | failed. Time to contact your | |
| 700 | | | local fossil guru. | |
| 701 | +-----------------------------------+-----------------------------------+ |
| 702 | | FOSSIL-1111 | Opening of file failed (e.g. POST | |
| 703 | | | data provided to CLI mode). | |
| 704 | +-----------------------------------+-----------------------------------+ |
| 705 | | | | |
| 706 | +-----------------------------------+-----------------------------------+ |
| 707 | | **FOSSIL-2000** | **Authentication/Access Error | |
| 708 | | | Category** | |
| 709 | +-----------------------------------+-----------------------------------+ |
| 710 | | FOSSIL-2001 | Privileged request was missing | |
| 711 | | | authentication token/cookie. | |
| 712 | +-----------------------------------+-----------------------------------+ |
| 713 | | FOSSIL-2002 | Access to requested resource was | |
| 714 | | | denied. Oftentimes the resultText | |
| 715 | | | property will contain a | |
| 716 | | | human-language description of the | |
| 717 | | | access rights needed for the | |
| 718 | | | given command. | |
| 719 | +-----------------------------------+-----------------------------------+ |
| 720 | | FOSSIL-2003 | Requested command is not | |
| 721 | | | available in the current | |
| 722 | | | operating mode. Returned in CLI | |
| 723 | | | mode by commands which require | |
| 724 | | | HTTP mode (e.g. login), and vice | |
| 725 | | | versa. | |
| 726 | +-----------------------------------+-----------------------------------+ |
| 727 | | | | |
| 728 | +-----------------------------------+-----------------------------------+ |
| 729 | | FOSSIL-2100 | Login Failed. | |
| 730 | +-----------------------------------+-----------------------------------+ |
| 731 | | FOSSIL-2101 | Anonymous login attempt is | |
| 732 | | | missing the "anonymousSeed" | |
| 733 | | | property (fetched via the | |
| 734 | | | /json/anonymousPassword request). | |
| 735 | | | Note that this is more specific | |
| 736 | | | form of FOSSIL-3002. | |
| 737 | +-----------------------------------+-----------------------------------+ |
| 738 | | | **ONLY FOR TESTING purposes | |
| 739 | | | should the remaning 210X | |
| 740 | | | sub-codes be enabled (they are | |
| 741 | | | potentially security-relevant, in | |
| 742 | | | that the client knows which part | |
| 743 | | | of the request was | |
| 744 | | | valid/invalid)** | |
| 745 | +-----------------------------------+-----------------------------------+ |
| 746 | | FOSSIL-2102 | Name not supplied in login | |
| 747 | | | request | |
| 748 | +-----------------------------------+-----------------------------------+ |
| 749 | | FOSSIL-2103 | Password not supplied in login | |
| 750 | | | request | |
| 751 | +-----------------------------------+-----------------------------------+ |
| 752 | | FOSSIL-2104 | No name/password match found | |
| 753 | +-----------------------------------+-----------------------------------+ |
| 754 | | | | |
| 755 | +-----------------------------------+-----------------------------------+ |
| 756 | | **FOSSIL-3000** | **Usage Error Category** | |
| 757 | +-----------------------------------+-----------------------------------+ |
| 758 | | FOSSIL-3001 | Invalid argument/parameter | |
| 759 | | | type(s) or value(s) in request | |
| 760 | +-----------------------------------+-----------------------------------+ |
| 761 | | FOSSIL-3002 | Required argument(s)/parameter(s) | |
| 762 | | | missing from request | |
| 763 | +-----------------------------------+-----------------------------------+ |
| 764 | | FOSSIL-3003 | Requested resource identifier is | |
| 765 | | | ambiguous (e.g. a shortened UUID | |
| 766 | | | can be ambiguous). | |
| 767 | +-----------------------------------+-----------------------------------+ |
| 768 | | FOSSIL-3004 | Unresolved resource identifier. A | |
| 769 | | | branch/tag/uuid provided by | |
| 770 | | | client code could not be | |
| 771 | | | resolved.\ | |
| 772 | | | This is a special case of #3006. | |
| 773 | +-----------------------------------+-----------------------------------+ |
| 774 | | FOSSIL-3005 | Resource already exists and | |
| 775 | | | overwriting/replacing is not | |
| 776 | | | allowed. e.g. trying to create a | |
| 777 | | | wiki page or user which already | |
| 778 | | | exists. | |
| 779 | | | | |
| 780 | | | FIXME? Consolidate this and | |
| 781 | | | resource-not-found into a | |
| 782 | | | separate category for dumb-down | |
| 783 | | | purposes? | |
| 784 | +-----------------------------------+-----------------------------------+ |
| 785 | | FOSSIL-3006 | Requested resource not found. e.g | |
| 786 | | | artifact ID, branch name, etc. | |
| 787 | +-----------------------------------+-----------------------------------+ |
| 788 | | | | |
| 789 | +-----------------------------------+-----------------------------------+ |
| 790 | | **FOSSIL-4000** | **Database-related Error | |
| 791 | | | Category** | |
| 792 | +-----------------------------------+-----------------------------------+ |
| 793 | | FOSSIL-4001 | Statement preparation failed. | |
| 794 | +-----------------------------------+-----------------------------------+ |
| 795 | | FOSSIL-4002 | Parameter binding failed. | |
| 796 | +-----------------------------------+-----------------------------------+ |
| 797 | | FOSSIL-4003 | Statement execution failed. | |
| 798 | +-----------------------------------+-----------------------------------+ |
| 799 | | FOSSIL-4004 | Database locked (this is not used | |
| 800 | | | anywhere, but reserved for future | |
| 801 | | | use). | |
| 802 | +-----------------------------------+-----------------------------------+ |
| 803 | | | **Special-case DB-related | |
| 804 | | | errors...** | |
| 805 | +-----------------------------------+-----------------------------------+ |
| 806 | | FOSSIL-4101 | Fossil Schema out of date (repo | |
| 807 | | | rebuild required). | |
| 808 | +-----------------------------------+-----------------------------------+ |
| 809 | | FOSSIL-4102 | Fossil repo db could not be | |
| 810 | | | found. | |
| 811 | +-----------------------------------+-----------------------------------+ |
| 812 | | FOSSIL-4103 | Repository db is not valid | |
| 813 | | | (possibly corrupt). | |
| 814 | +-----------------------------------+-----------------------------------+ |
| 815 | | FOSSIL-4104 | Check-out not found. This is | |
| 816 | | | similar to FOSSIL-4102 but | |
| 817 | | | indicates that a local checkout | |
| 818 | | | is required (but was not found). | |
| 819 | | | Note that the 4102 gets triggered | |
| 820 | | | earlier than this one, and so can | |
| 821 | | | appear in cases when a user might | |
| 822 | | | otherwise expect a 4104 error. | |
| 823 | +-----------------------------------+-----------------------------------+ |
| 824 | ``` |
| 825 | |
| 826 | Some of those error codes are of course "too detailed" for the client to |
| 827 | do anything with (e.g.. 4001-4004), but their intention is to make it |
| 828 | easier for Fossil developers to (A) track down problems and (B) support |
| 829 | clients who report problems. If a client reports, "I get a FOSSIL-4000, |
| 830 |
| --- www/json-api/conventions.md | |
| +++ www/json-api/conventions.md | |
| @@ -3,11 +3,12 @@ | |
| 3 | |
| 4 | Jump to: |
| 5 | |
| 6 | * [JSON Property Naming](#property-names) |
| 7 | * [HTTP GET Requests](#http-get) |
| 8 | * [HTTP POST Requests](#http-post) |
| 9 | * [POST Request Envelope](#request-envelope) |
| 10 | * [Request Parameter Data Types](#request-param-types) |
| 11 | * [Response Envelope](#response-envelope) |
| 12 | * [HTTP Response Headers](#http-response-header) |
| 13 | * [CLI vs. HTTP Mode](#cli-vs-http) |
| 14 | * [Simulating POSTed data](#simulating-post-data) |
| @@ -27,22 +28,23 @@ | |
| 28 | |
| 29 | <a id="http-get"></a> |
| 30 | # HTTP GET Requests |
| 31 | |
| 32 | Many (if not most) requests can be made via simple GET requests, e.g. we |
| 33 | *could* use any of the following patterns for a hypothetical JSON-format |
| 34 | timeline: |
| 35 | |
| 36 | - `https://..../timeline/json` |
| 37 | - `/timeline?format=json` |
| 38 | - `/timeline?json=1` |
| 39 | - `/timeline.json` |
| 40 | - `/json/timeline?...options...` |
| 41 | |
| 42 | The API settled on the `/json/...` convention, primarily because it |
| 43 | simplifies dispatching and argument-handling logic compared to the |
| 44 | `/[.../]foo.json` approach. Using `/json/...` allows us to unify that |
| 45 | logic for all JSON sub-commands, for both CLI and HTTP modes. |
| 46 | |
| 47 | <a id="http-post"></a> |
| 48 | # HTTP Post Requests |
| 49 | |
| 50 | Certain requests, mainly things like editing checkin messages and |
| @@ -56,86 +58,42 @@ | |
| 58 | |
| 59 | POST requests are sent to the same URL as their GET counterpart (if any, |
| 60 | else their own path), and are sent as plain-text/unencoded JSON wrapped |
| 61 | in a common request envelope with the following properties: |
| 62 | |
| 63 | - `requestId`: Optional arbitrary JSON value, not used by fossil, but |
| 64 | returned as-is in responses. |
| 65 | - `command`: Provides a secondary mechanism for specifying which JSON |
| 66 | command should be run. A request path of /json/foo/bar is equivalent |
| 67 | to a request with path=/json and command=foo/bar. Note that subpaths |
| 68 | do not work this way. e.g. path=/json/foo, command=bar will not |
| 69 | work, but path=/json, command=foo/bar will. This option is |
| 70 | particularly useful when generating JSON for piping in to CLI mode, |
| 71 | but it also has some response-dispatching uses on the client side. |
| 72 | - `authToken`: Authentication token. Created by a login |
| 73 | request. Determines what access rights the user has, and any given |
| 74 | request may require specific rights. In principle this is required |
| 75 | by any request which needs non-guest privileges, but cookie-aware |
| 76 | clients do not manually need to track this (it is managed as a |
| 77 | cookie by the agent/browser). |
| 78 | - `payload`: Command-specific parameters. Most can optionally come in |
| 79 | via GET parameters, but those taking complex structures expect them |
| 80 | to be placed here. |
| 81 | - `indent`: Optionally specifies indentation for the output. 0=no |
| 82 | indention. 1=a single TAB character for each level of |
| 83 | indentation. >1 means that many spaces per level. e.g. indent=7 |
| 84 | means to indent 7 spaces per object/array depth level. cson also |
| 85 | supports other flags for fine-tuning the output spacing, and adding |
| 86 | them to this interface might be interesting at some |
| 87 | point. e.g. whether or not to add a newline to the output. CLI mode |
| 88 | adds extra indentation by default, whereas CGI/server modes produce |
| 89 | unindented output by default. |
| 90 | - `jsonp`: Optional String (client function name). Requests which |
| 91 | include this will be returned with `Content-Type |
| 92 | application/javascript` and will be wrapped up in a function call |
| 93 | using the given name. e.g. if `jsonp=foo` then the result would look like:\ |
| 94 | `foo( {...the response envelope...} )` |
| 95 | |
| 96 | The API allows most of those (normally all but the payload) to come in |
| 97 | as either GET parameters or properties of the top-level POSTed request |
| 98 | JSON envelope, with GET taking priority over POST. (Reminder to self: we |
| 99 | could potentially also use values from cookies. Fossil currently only |
| @@ -180,16 +138,17 @@ | |
| 138 | } |
| 139 | } |
| 140 | ``` |
| 141 | |
| 142 | When a given parameter is set in two places, e.g. GET and POST, or |
| 143 | POST-from-a-file and CLI parameters, which one takes precedence |
| 144 | depends on the concrete command handler (and may be unspecified). Most |
| 145 | will give precedence to CLI and GET parameters, but POSTed values are |
| 146 | technically preferred for non-string data because no additional "type |
| 147 | guessing" or string-to-whatever conversion has to be made (GET/CLI |
| 148 | parameters are *always* strings, even if they look like a number or |
| 149 | boolean). |
| 150 | |
| 151 | |
| 152 | <a id="request-param-types"></a> |
| 153 | # Request Parameter Data Types |
| 154 | |
| @@ -245,140 +204,71 @@ | |
| 204 | |
| 205 | Every response comes in the form of a HTTP response or (in CLI mode) |
| 206 | JSON sent to stdout. The body of the response is a JSON object following |
| 207 | a common envelope format. The envelope has the following properties: |
| 208 | |
| 209 | |
| 210 | - `fossil`: Fossil server version string. This property is basically |
| 211 | "the official response envelope marker" - if it is set, clients can |
| 212 | "probably safely assume" that the object indeed came from one of the |
| 213 | Fossil/JSON APIs. This API never creates responses which do not |
| 214 | contain this property. |
| 215 | - `requestId`: Only set if the request contained it, and then it is |
| 216 | echoed back to the caller as-is. This can be use to determine |
| 217 | (client-side) which request a given response is coming in for |
| 218 | (assuming multiple asynchronous requests are pending). In practice |
| 219 | this generally isn’t needed because response handling tends to be |
| 220 | done by closures associated with the original request object (at |
| 221 | least in JavaScript code). In languages without closures it might |
| 222 | have some use. It may be any legal JSON value - it need not be |
| 223 | confined to a string or number. |
| 224 | - `resultCode`: Standardized result code string in the form |
| 225 | `FOSSIL-####`. Only error responses contain a `resultCode`. |
| 226 | - `resultText`: Possibly a descriptive string, possibly |
| 227 | empty. Supplements the resultCode, but can also be set on success |
| 228 | responses (but normally isn't). Clients must not rely on any |
| 229 | specific values being set here. |
| 230 | - `payload`: Request-specific response payload (data type/structure is |
| 231 | request-specific). The payload is never set for error responses, |
| 232 | only for success responses (and only those which actually have a |
| 233 | payload - not all do). |
| 234 | - `timestamp`: Response timestamp (GMT Unix Epoch). We use seconds |
| 235 | precision because i did not know at the time that Fossil actually |
| 236 | records millisecond precision. |
| 237 | - `payloadVersion`: Not initially needed, but reserved for future use |
| 238 | in maintaining version compatibility when the format of a given |
| 239 | response type's payload changes. If needed, the "first version" |
| 240 | value is assumed to be 0, for semantic [near-]compatibility with the |
| 241 | undefined value clients see when this property is not set. |
| 242 | - `command`: Normalized form of the command being run. It consists of |
| 243 | the "command" (non-argument) parts of the request path (or CLI |
| 244 | positional arguments), excluding the initial "/json/" part. e.g. the |
| 245 | "command" part of "/json/timeline/checkin?a=b" (CLI: json timeline |
| 246 | checkin...) is "timeline/checkin" (both in CLI and HTTP modes). |
| 247 | - `apiVersion`: Not yet used, but reserved for a numeric value which |
| 248 | represents the JSON API's version (which can be used to determine if |
| 249 | it has a given feature or not). This will not be implemented until |
| 250 | it's needed. |
| 251 | - `warnings`: Reserved for future use as a standard place to put |
| 252 | non-fatal warnings in responses. Will be an array but the warning |
| 253 | structure/type is not yet specified. Intended primarily as a |
| 254 | debugging tool, and will "probably not" become part of the public |
| 255 | client interface. |
| 256 | - `g`: Fossil administrators (those with the "a" or "s" permissions) |
| 257 | may use the debugFossilG boolean request parameter (CLI: |
| 258 | --json-debug-g) to enable this property for any given response. It |
| 259 | contains a good deal of the server-side internal state at the time |
| 260 | the response was generated, which is often useful in debuggering |
| 261 | problems. Trivia: it is called "g" because that's the name of |
| 262 | fossil's internal global state object. |
| 263 | - `procTimeMs`: For debugging only - generic clients must not rely on |
| 264 | this property. Contains the number of milliseconds the JSON command |
| 265 | processor needed to dispatch and process the command. TODO: move the |
| 266 | timer into the fossil core so that we can generically time its |
| 267 | responses and include the startup overhead in the time calculation. |
| 268 | |
| 269 | |
| 270 | |
| 271 | <a id="http-response-header"></a> |
| 272 | # HTTP Response Headers |
| 273 | |
| 274 | The Content-Type HTTP header of a response will be either |
| @@ -615,215 +505,115 @@ | |
| 505 | [`src/json.c:json_err_cstr()`](/finfo/src/json.c). Changes there need |
| 506 | to be reflected here (and vice versa). Also, we have assertions in |
| 507 | place to ensure that C-side codes are in the range 1000-9999, so do |
| 508 | not just go blindly change the numeric ranges used by the enum. |
| 509 | |
| 510 | |
| 511 | **`FOSSIL-0###`: Non-error Category** |
| 512 | |
| 513 | - `FOSSIL-0000`: Success/not an error. Succesful responses do not |
| 514 | contain a resultCode, so clients should never see this. |
| 515 | - `FOSSIL-0###`: Reserved for potential future use in reporting |
| 516 | non-fatal warnings. |
| 517 | |
| 518 | |
| 519 | |
| 520 | **`FOSSIL-1000`: Generic Errors Category** |
| 521 | |
| 522 | - `FOSSIL-1101`: Invalid request. Request envelope is invalid or |
| 523 | missing. |
| 524 | - `FOSSIL-1102`: Unknown JSON command. |
| 525 | - `FOSSIL-1103`: Unknown/unspecified error |
| 526 | - `FOSSIL-1104`: RE-USE |
| 527 | - `FOSSIL-1105`: A server-side timeout was reached. (i’m not sure we |
| 528 | can actually implement this one, though.) |
| 529 | - `FOSSIL-1106`: Assertion failed (or would have had we |
| 530 | continued). Note: if an `assert()` fails in CGI/server modes, the HTTP |
| 531 | response will be code 500 (Internal Server Error). We want to avoid |
| 532 | that and return a JSON response instead. All of that said - there seems |
| 533 | to be little reason to implementi this, since assertions are "truly |
| 534 | serious" errors. |
| 535 | - `FOSSIL-1107`: Allocation/out of memory error. This cannot be reasonably |
| 536 | reported because fossil aborts if an allocation fails. |
| 537 | - `FOSSIL-1108`: Requested API is not yet implemented. |
| 538 | - `FOSSIL-1109`: Panic! Fossil's `fossil_panic()` or `cgi_panic()` was |
| 539 | called. In non-JSON HTML mode this produces an HTTP 500 |
| 540 | error. Clients "should" report this as a potential bug, as it |
| 541 | "possibly" indicates that the C code has incorrect argument- or |
| 542 | error handling somewhere. |
| 543 | - `FOSSIL-1110`: Reading of artifact manifest failed. Time to contact |
| 544 | your local fossil guru. |
| 545 | - `FOSSIL-1111`: Opening of file failed (e.g. POST data provided to |
| 546 | CLI mode). |
| 547 | |
| 548 | |
| 549 | **`FOSSIL-2000`: Authentication/Access Error Category** |
| 550 | |
| 551 | - `FOSSIL-2001`: Privileged request was missing authentication |
| 552 | token/cookie. |
| 553 | - `FOSSIL-2002`: Access to requested resource was denied. Oftentimes |
| 554 | the `resultText` property will contain a human-language description of |
| 555 | the access rights needed for the given command. |
| 556 | - `FOSSIL-2003`: Requested command is not available in the current |
| 557 | operating mode. Returned in CLI mode by commands which require HTTP |
| 558 | mode (e.g. login), and vice versa. FIXME: now that we can simulate |
| 559 | POST in CLI mode, we can get rid of this distinction for some of the |
| 560 | commands. |
| 561 | - `FOSSIL-2100`: Login Failed. |
| 562 | - `FOSSIL-2101`: Anonymous login attempt is missing the |
| 563 | "anonymousSeed" property (fetched via [the `/json/anonymousPassword` |
| 564 | request](api-auth.md#login-anonymous)). Note that this is more |
| 565 | specific form of `FOSSIL-3002`. |
| 566 | |
| 567 | |
| 568 | ONLY FOR TESTING purposes should the remaning 210X sub-codes be |
| 569 | enabled (they are potentially security-relevant, in that the client |
| 570 | knows which part of the request was valid/invalid): |
| 571 | |
| 572 | - `FOSSIL-2102`: Name not supplied in login request |
| 573 | - `FOSSIL-2103`: Password not supplied in login request |
| 574 | - `FOSSIL-2104`: No name/password match found |
| 575 | |
| 576 | |
| 577 | **`FOSSIL-3000`: Usage Error Category** |
| 578 | |
| 579 | - `FOSSIL-3001`: Invalid argument/parameter type(s) or value(s) in |
| 580 | request |
| 581 | - `FOSSIL-3002`: Required argument(s)/parameter(s) missing from |
| 582 | request |
| 583 | - `FOSSIL-3003`: Requested resource identifier is ambiguous (e.g. a |
| 584 | shortened UUID can be ambiguous). |
| 585 | - `FOSSIL-3004`: Unresolved resource identifier. A branch/tag/uuid |
| 586 | provided by client code could not be resolved. This is a special |
| 587 | case of #3006. |
| 588 | - `FOSSIL-3005`: Resource already exists and overwriting/replacing is |
| 589 | not allowed. e.g. trying to create a wiki page or user which already |
| 590 | exists. FIXME? Consolidate this and resource-not-found into a |
| 591 | separate category for dumb-down purposes? |
| 592 | - `FOSSIL-3006`: Requested resource not found. e.g artifact ID, branch |
| 593 | name, etc. |
| 594 | |
| 595 | |
| 596 | **`FOSSIL-4000`: Database-related Error Category** |
| 597 | |
| 598 | - `FOSSIL-4001`: Statement preparation failed. |
| 599 | - `FOSSIL-4002`: Parameter binding failed. |
| 600 | - `FOSSIL-4003`: Statement execution failed. |
| 601 | - `FOSSIL-4004`: Database locked (this is not used anywhere, but |
| 602 | reserved for future use). |
| 603 | |
| 604 | Special-case DB-related errors... |
| 605 | |
| 606 | - `FOSSIL-4101`: Fossil Schema out of date (repo rebuild required). |
| 607 | - `FOSSIL-4102`: Fossil repo db could not be found. |
| 608 | - `FOSSIL-4103`: Repository db is not valid (possibly corrupt). |
| 609 | - `FOSSIL-4104`: Check-out not found. This is similar to FOSSIL-4102 |
| 610 | but indicates that a local checkout is required (but was not |
| 611 | found). Note that the 4102 gets triggered earlier than this one, and |
| 612 | so can appear in cases when a user might otherwise expect a 4104 |
| 613 | error. |
| 614 | |
| 615 | |
| 616 | Some of those error codes are of course "too detailed" for the client to |
| 617 | do anything with (e.g.. 4001-4004), but their intention is to make it |
| 618 | easier for Fossil developers to (A) track down problems and (B) support |
| 619 | clients who report problems. If a client reports, "I get a FOSSIL-4000, |
| 620 |
+30
-6
| --- www/json-api/index.md | ||
| +++ www/json-api/index.md | ||
| @@ -1,15 +1,39 @@ | ||
| 1 | 1 | # JSON API Index |
| 2 | 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 | - | |
| 7 | 3 | This is the client-side documentation of Fossil's JSON API. The JSON |
| 8 | -API aims to provide access to most of the primary fossil features via | |
| 4 | +API aims to provide access to many of the primary fossil features via | |
| 9 | 5 | AJAX-style interfaces. |
| 10 | 6 | |
| 11 | 7 | * [Introduction](intro.md) |
| 12 | 8 | * [General API Conventions](conventions.md) |
| 13 | 9 | * [Tips & Tricks](tips.md) |
| 14 | 10 | * [Hacking Guide](hacking.md) |
| 15 | -* [APIs](api-index.md) | |
| 11 | + | |
| 12 | +General warnings regarding the APIs linked to in the following list: | |
| 13 | + | |
| 14 | +- **NOTE** that request/response examples shown in the individual API | |
| 15 | +pages do not show [the standard request/response envelope](conventions.md) | |
| 16 | +(for brevity and sanity). | |
| 17 | +- **Achtung:** just because a given feature is described as being | |
| 18 | +implemented does not mean that the implementation is "final" - it may be | |
| 19 | +changed at any time until we find/implement useful APIs. | |
| 20 | + | |
| 21 | +The APIs, alphabetically by category: | |
| 22 | + | |
| 23 | +* [Artifact Info](api-artifact.md) | |
| 24 | +* [Authentication](api-auth.md) | |
| 25 | +* [Branches](api-branch.md) | |
| 26 | +* [Checkout Status](api-checkout.md) | |
| 27 | +* [Config](api-config.md) | |
| 28 | +* [Diffs](api-diff.md) | |
| 29 | +* [Directory Listing](api-dir.md) | |
| 30 | +* [File Info](api-finfo.md) | |
| 31 | +* [The Obligatory Misc. Category](api-misc.md) | |
| 32 | +* [Repository Stats](api-stat.md) | |
| 33 | +* [SQL Query](api-query.md) | |
| 34 | +* [Tags](api-tag.md) | |
| 35 | +* [Tickets](api-ticket.md) | |
| 36 | +* [Timeline](api-timeline.md) | |
| 37 | +* [User Management](api-user.md) | |
| 38 | +* [Version](api-version.md) | |
| 39 | +* [Wiki](api-wiki.md) | |
| 16 | 40 |
| --- www/json-api/index.md | |
| +++ www/json-api/index.md | |
| @@ -1,15 +1,39 @@ | |
| 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 | |
| 7 | This is the client-side documentation of Fossil's JSON API. The JSON |
| 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 |
| --- www/json-api/index.md | |
| +++ www/json-api/index.md | |
| @@ -1,15 +1,39 @@ | |
| 1 | # JSON API Index |
| 2 | |
| 3 | This is the client-side documentation of Fossil's JSON API. The JSON |
| 4 | API aims to provide access to many of the primary fossil features via |
| 5 | AJAX-style interfaces. |
| 6 | |
| 7 | * [Introduction](intro.md) |
| 8 | * [General API Conventions](conventions.md) |
| 9 | * [Tips & Tricks](tips.md) |
| 10 | * [Hacking Guide](hacking.md) |
| 11 | |
| 12 | General warnings regarding the APIs linked to in the following list: |
| 13 | |
| 14 | - **NOTE** that request/response examples shown in the individual API |
| 15 | pages do not show [the standard request/response envelope](conventions.md) |
| 16 | (for brevity and sanity). |
| 17 | - **Achtung:** just because a given feature is described as being |
| 18 | implemented does not mean that the implementation is "final" - it may be |
| 19 | changed at any time until we find/implement useful APIs. |
| 20 | |
| 21 | The APIs, alphabetically by category: |
| 22 | |
| 23 | * [Artifact Info](api-artifact.md) |
| 24 | * [Authentication](api-auth.md) |
| 25 | * [Branches](api-branch.md) |
| 26 | * [Checkout Status](api-checkout.md) |
| 27 | * [Config](api-config.md) |
| 28 | * [Diffs](api-diff.md) |
| 29 | * [Directory Listing](api-dir.md) |
| 30 | * [File Info](api-finfo.md) |
| 31 | * [The Obligatory Misc. Category](api-misc.md) |
| 32 | * [Repository Stats](api-stat.md) |
| 33 | * [SQL Query](api-query.md) |
| 34 | * [Tags](api-tag.md) |
| 35 | * [Tickets](api-ticket.md) |
| 36 | * [Timeline](api-timeline.md) |
| 37 | * [User Management](api-user.md) |
| 38 | * [Version](api-version.md) |
| 39 | * [Wiki](api-wiki.md) |
| 40 |