Fossil SCM
(Typos) www/json/conventions.md - Various fixes.
Commit
9d9193fd4db6cdbc386e148b026e284bf0a96cd1e624687b9ee68eb65a1c8550
Parent
33771ff04f7cc43…
1 file changed
+8
-8
+8
-8
| --- www/json-api/conventions.md | ||
| +++ www/json-api/conventions.md | ||
| @@ -100,11 +100,11 @@ | ||
| 100 | 100 | |
| 101 | 101 | The API allows most of those (normally all but the payload) to come in |
| 102 | 102 | as either GET parameters or properties of the top-level POSTed request |
| 103 | 103 | JSON envelope, with GET taking priority over POST. (Reminder to self: we |
| 104 | 104 | could potentially also use values from cookies. Fossil currently only |
| 105 | -uses 1 cookie (the login token), and i'd prefer to keep it that way.) | |
| 105 | +uses 1 cookie (the login token), and I'd prefer to keep it that way.) | |
| 106 | 106 | |
| 107 | 107 | POST requests without such an envelope will be rejected, generating a |
| 108 | 108 | Fossil/JSON error response (as opposed to an HTTP error response). GET |
| 109 | 109 | requests, by definition, never have an envelope. |
| 110 | 110 | |
| @@ -169,11 +169,11 @@ | ||
| 169 | 169 | No higher-level constructs, e.g. JSON **arrays** or **objects**, are |
| 170 | 170 | accepted in string form. Such parameters must be set in the POST |
| 171 | 171 | envelope or payload, as specified by the specific API. |
| 172 | 172 | |
| 173 | 173 | This API does not currently use any **floating-point** parameters, but |
| 174 | -does return floating-point results in a couple places. | |
| 174 | +does return floating-point results in a couple of places. | |
| 175 | 175 | |
| 176 | 176 | For **integer** parameters we use a conventional string-to-int algorithm |
| 177 | 177 | and assume base 10 (analog to atoi(3)). The API may err on the side of |
| 178 | 178 | usability when given technically invalid values. e.g. "123abc" will |
| 179 | 179 | likely be interpreted as the integer 123. No APIs currently rely on |
| @@ -205,11 +205,11 @@ | ||
| 205 | 205 | cause inconsistencies vis-a-vis the HTML interface). |
| 206 | 206 | |
| 207 | 207 | <a id="response-envelope"></a> |
| 208 | 208 | # Response Envelope |
| 209 | 209 | |
| 210 | -Every response comes in the form of a HTTP response or (in CLI mode) | |
| 210 | +Every response comes in the form of an HTTP response or (in CLI mode) | |
| 211 | 211 | JSON sent to stdout. The body of the response is a JSON object following |
| 212 | 212 | a common envelope format. The envelope has the following properties: |
| 213 | 213 | |
| 214 | 214 | |
| 215 | 215 | - `fossil`: Fossil server version string. This property is basically |
| @@ -216,11 +216,11 @@ | ||
| 216 | 216 | "the official response envelope marker" - if it is set, clients can |
| 217 | 217 | "probably safely assume" that the object indeed came from one of the |
| 218 | 218 | Fossil/JSON APIs. This API never creates responses which do not |
| 219 | 219 | contain this property. |
| 220 | 220 | - `requestId`: Only set if the request contained it, and then it is |
| 221 | - echoed back to the caller as-is. This can be use to determine | |
| 221 | + echoed back to the caller as-is. This can be used to determine | |
| 222 | 222 | (client-side) which request a given response is coming in for |
| 223 | 223 | (assuming multiple asynchronous requests are pending). In practice |
| 224 | 224 | this generally isn’t needed because response handling tends to be |
| 225 | 225 | done by closures associated with the original request object (at |
| 226 | 226 | least in JavaScript code). In languages without closures it might |
| @@ -235,11 +235,11 @@ | ||
| 235 | 235 | - `payload`: Request-specific response payload (data type/structure is |
| 236 | 236 | request-specific). The payload is never set for error responses, |
| 237 | 237 | only for success responses (and only those which actually have a |
| 238 | 238 | payload - not all do). |
| 239 | 239 | - `timestamp`: Response timestamp (GMT Unix Epoch). We use seconds |
| 240 | - precision because i did not know at the time that Fossil actually | |
| 240 | + precision because I did not know at the time that Fossil actually | |
| 241 | 241 | records millisecond precision. |
| 242 | 242 | - `payloadVersion`: Not initially needed, but reserved for future use |
| 243 | 243 | in maintaining version compatibility when the format of a given |
| 244 | 244 | response type's payload changes. If needed, the "first version" |
| 245 | 245 | value is assumed to be 0, for semantic [near-]compatibility with the |
| @@ -402,11 +402,11 @@ | ||
| 402 | 402 | (they are represented by `\t`) there is no chance that such a global |
| 403 | 403 | replacement will corrupt JSON string contents - only the formatting will |
| 404 | 404 | be affected. |
| 405 | 405 | |
| 406 | 406 | Potential TODO: because extraneous indention "could potentially" be used |
| 407 | -as a form DoS, the option *might* be subject to later removed from HTTP | |
| 407 | +as a form of DoS, the option *might* be subject to later removal from HTTP | |
| 408 | 408 | mode (in CLI it's fine). |
| 409 | 409 | |
| 410 | 410 | In HTTP mode no trailing newline is added to the output, whereas in CLI |
| 411 | 411 | mode one is normally appended (exception: in JSONP mode no newline is |
| 412 | 412 | appended, to (rather pedantically and arbitraily) allow the client to |
| @@ -482,11 +482,11 @@ | ||
| 482 | 482 | normally want to see very specific error codes when tracking down a |
| 483 | 483 | problem. We can offer a configuration option to "dumb down" error |
| 484 | 484 | codes to their generic category by simply doing a modulo 100 |
| 485 | 485 | (or 1000) against the native error code number. e.g. FOSSIL-1271 |
| 486 | 486 | could (via a simple modulo) be reduced to FOSSIL-1200 or |
| 487 | - FOSSIL-1000, depending on the paranoia level of the sysadmin. i have | |
| 487 | + FOSSIL-1000, depending on the paranoia level of the sysadmin. I have | |
| 488 | 488 | tried to order the result code numbers so that a dumb-down level of |
| 489 | 489 | 2 provides reasonably usable results without giving away too much |
| 490 | 490 | detail to malicious clients.\ |
| 491 | 491 | (**TODO:** `g.json.errorDetailParanoia` is used to set the |
| 492 | 492 | default dumb-down level, but it is currently set at compile-time. |
| @@ -533,11 +533,11 @@ | ||
| 533 | 533 | can actually implement this one, though.) |
| 534 | 534 | - `FOSSIL-1106`: Assertion failed (or would have had we |
| 535 | 535 | continued). Note: if an `assert()` fails in CGI/server modes, the HTTP |
| 536 | 536 | response will be code 500 (Internal Server Error). We want to avoid |
| 537 | 537 | that and return a JSON response instead. All of that said - there seems |
| 538 | - to be little reason to implementi this, since assertions are "truly | |
| 538 | + to be little reason to implement this, since assertions are "truly | |
| 539 | 539 | serious" errors. |
| 540 | 540 | - `FOSSIL-1107`: Allocation/out of memory error. This cannot be reasonably |
| 541 | 541 | reported because fossil aborts if an allocation fails. |
| 542 | 542 | - `FOSSIL-1108`: Requested API is not yet implemented. |
| 543 | 543 | - `FOSSIL-1109`: Panic! Fossil's `fossil_panic()` or `cgi_panic()` was |
| 544 | 544 |
| --- www/json-api/conventions.md | |
| +++ www/json-api/conventions.md | |
| @@ -100,11 +100,11 @@ | |
| 100 | |
| 101 | The API allows most of those (normally all but the payload) to come in |
| 102 | as either GET parameters or properties of the top-level POSTed request |
| 103 | JSON envelope, with GET taking priority over POST. (Reminder to self: we |
| 104 | could potentially also use values from cookies. Fossil currently only |
| 105 | uses 1 cookie (the login token), and i'd prefer to keep it that way.) |
| 106 | |
| 107 | POST requests without such an envelope will be rejected, generating a |
| 108 | Fossil/JSON error response (as opposed to an HTTP error response). GET |
| 109 | requests, by definition, never have an envelope. |
| 110 | |
| @@ -169,11 +169,11 @@ | |
| 169 | No higher-level constructs, e.g. JSON **arrays** or **objects**, are |
| 170 | accepted in string form. Such parameters must be set in the POST |
| 171 | envelope or payload, as specified by the specific API. |
| 172 | |
| 173 | This API does not currently use any **floating-point** parameters, but |
| 174 | does return floating-point results in a couple places. |
| 175 | |
| 176 | For **integer** parameters we use a conventional string-to-int algorithm |
| 177 | and assume base 10 (analog to atoi(3)). The API may err on the side of |
| 178 | usability when given technically invalid values. e.g. "123abc" will |
| 179 | likely be interpreted as the integer 123. No APIs currently rely on |
| @@ -205,11 +205,11 @@ | |
| 205 | cause inconsistencies vis-a-vis the HTML interface). |
| 206 | |
| 207 | <a id="response-envelope"></a> |
| 208 | # Response Envelope |
| 209 | |
| 210 | Every response comes in the form of a HTTP response or (in CLI mode) |
| 211 | JSON sent to stdout. The body of the response is a JSON object following |
| 212 | a common envelope format. The envelope has the following properties: |
| 213 | |
| 214 | |
| 215 | - `fossil`: Fossil server version string. This property is basically |
| @@ -216,11 +216,11 @@ | |
| 216 | "the official response envelope marker" - if it is set, clients can |
| 217 | "probably safely assume" that the object indeed came from one of the |
| 218 | Fossil/JSON APIs. This API never creates responses which do not |
| 219 | contain this property. |
| 220 | - `requestId`: Only set if the request contained it, and then it is |
| 221 | echoed back to the caller as-is. This can be use to determine |
| 222 | (client-side) which request a given response is coming in for |
| 223 | (assuming multiple asynchronous requests are pending). In practice |
| 224 | this generally isn’t needed because response handling tends to be |
| 225 | done by closures associated with the original request object (at |
| 226 | least in JavaScript code). In languages without closures it might |
| @@ -235,11 +235,11 @@ | |
| 235 | - `payload`: Request-specific response payload (data type/structure is |
| 236 | request-specific). The payload is never set for error responses, |
| 237 | only for success responses (and only those which actually have a |
| 238 | payload - not all do). |
| 239 | - `timestamp`: Response timestamp (GMT Unix Epoch). We use seconds |
| 240 | precision because i did not know at the time that Fossil actually |
| 241 | records millisecond precision. |
| 242 | - `payloadVersion`: Not initially needed, but reserved for future use |
| 243 | in maintaining version compatibility when the format of a given |
| 244 | response type's payload changes. If needed, the "first version" |
| 245 | value is assumed to be 0, for semantic [near-]compatibility with the |
| @@ -402,11 +402,11 @@ | |
| 402 | (they are represented by `\t`) there is no chance that such a global |
| 403 | replacement will corrupt JSON string contents - only the formatting will |
| 404 | be affected. |
| 405 | |
| 406 | Potential TODO: because extraneous indention "could potentially" be used |
| 407 | as a form DoS, the option *might* be subject to later removed from HTTP |
| 408 | mode (in CLI it's fine). |
| 409 | |
| 410 | In HTTP mode no trailing newline is added to the output, whereas in CLI |
| 411 | mode one is normally appended (exception: in JSONP mode no newline is |
| 412 | appended, to (rather pedantically and arbitraily) allow the client to |
| @@ -482,11 +482,11 @@ | |
| 482 | normally want to see very specific error codes when tracking down a |
| 483 | problem. We can offer a configuration option to "dumb down" error |
| 484 | codes to their generic category by simply doing a modulo 100 |
| 485 | (or 1000) against the native error code number. e.g. FOSSIL-1271 |
| 486 | could (via a simple modulo) be reduced to FOSSIL-1200 or |
| 487 | FOSSIL-1000, depending on the paranoia level of the sysadmin. i have |
| 488 | tried to order the result code numbers so that a dumb-down level of |
| 489 | 2 provides reasonably usable results without giving away too much |
| 490 | detail to malicious clients.\ |
| 491 | (**TODO:** `g.json.errorDetailParanoia` is used to set the |
| 492 | default dumb-down level, but it is currently set at compile-time. |
| @@ -533,11 +533,11 @@ | |
| 533 | can actually implement this one, though.) |
| 534 | - `FOSSIL-1106`: Assertion failed (or would have had we |
| 535 | continued). Note: if an `assert()` fails in CGI/server modes, the HTTP |
| 536 | response will be code 500 (Internal Server Error). We want to avoid |
| 537 | that and return a JSON response instead. All of that said - there seems |
| 538 | to be little reason to implementi this, since assertions are "truly |
| 539 | serious" errors. |
| 540 | - `FOSSIL-1107`: Allocation/out of memory error. This cannot be reasonably |
| 541 | reported because fossil aborts if an allocation fails. |
| 542 | - `FOSSIL-1108`: Requested API is not yet implemented. |
| 543 | - `FOSSIL-1109`: Panic! Fossil's `fossil_panic()` or `cgi_panic()` was |
| 544 |
| --- www/json-api/conventions.md | |
| +++ www/json-api/conventions.md | |
| @@ -100,11 +100,11 @@ | |
| 100 | |
| 101 | The API allows most of those (normally all but the payload) to come in |
| 102 | as either GET parameters or properties of the top-level POSTed request |
| 103 | JSON envelope, with GET taking priority over POST. (Reminder to self: we |
| 104 | could potentially also use values from cookies. Fossil currently only |
| 105 | uses 1 cookie (the login token), and I'd prefer to keep it that way.) |
| 106 | |
| 107 | POST requests without such an envelope will be rejected, generating a |
| 108 | Fossil/JSON error response (as opposed to an HTTP error response). GET |
| 109 | requests, by definition, never have an envelope. |
| 110 | |
| @@ -169,11 +169,11 @@ | |
| 169 | No higher-level constructs, e.g. JSON **arrays** or **objects**, are |
| 170 | accepted in string form. Such parameters must be set in the POST |
| 171 | envelope or payload, as specified by the specific API. |
| 172 | |
| 173 | This API does not currently use any **floating-point** parameters, but |
| 174 | does return floating-point results in a couple of places. |
| 175 | |
| 176 | For **integer** parameters we use a conventional string-to-int algorithm |
| 177 | and assume base 10 (analog to atoi(3)). The API may err on the side of |
| 178 | usability when given technically invalid values. e.g. "123abc" will |
| 179 | likely be interpreted as the integer 123. No APIs currently rely on |
| @@ -205,11 +205,11 @@ | |
| 205 | cause inconsistencies vis-a-vis the HTML interface). |
| 206 | |
| 207 | <a id="response-envelope"></a> |
| 208 | # Response Envelope |
| 209 | |
| 210 | Every response comes in the form of an HTTP response or (in CLI mode) |
| 211 | JSON sent to stdout. The body of the response is a JSON object following |
| 212 | a common envelope format. The envelope has the following properties: |
| 213 | |
| 214 | |
| 215 | - `fossil`: Fossil server version string. This property is basically |
| @@ -216,11 +216,11 @@ | |
| 216 | "the official response envelope marker" - if it is set, clients can |
| 217 | "probably safely assume" that the object indeed came from one of the |
| 218 | Fossil/JSON APIs. This API never creates responses which do not |
| 219 | contain this property. |
| 220 | - `requestId`: Only set if the request contained it, and then it is |
| 221 | echoed back to the caller as-is. This can be used to determine |
| 222 | (client-side) which request a given response is coming in for |
| 223 | (assuming multiple asynchronous requests are pending). In practice |
| 224 | this generally isn’t needed because response handling tends to be |
| 225 | done by closures associated with the original request object (at |
| 226 | least in JavaScript code). In languages without closures it might |
| @@ -235,11 +235,11 @@ | |
| 235 | - `payload`: Request-specific response payload (data type/structure is |
| 236 | request-specific). The payload is never set for error responses, |
| 237 | only for success responses (and only those which actually have a |
| 238 | payload - not all do). |
| 239 | - `timestamp`: Response timestamp (GMT Unix Epoch). We use seconds |
| 240 | precision because I did not know at the time that Fossil actually |
| 241 | records millisecond precision. |
| 242 | - `payloadVersion`: Not initially needed, but reserved for future use |
| 243 | in maintaining version compatibility when the format of a given |
| 244 | response type's payload changes. If needed, the "first version" |
| 245 | value is assumed to be 0, for semantic [near-]compatibility with the |
| @@ -402,11 +402,11 @@ | |
| 402 | (they are represented by `\t`) there is no chance that such a global |
| 403 | replacement will corrupt JSON string contents - only the formatting will |
| 404 | be affected. |
| 405 | |
| 406 | Potential TODO: because extraneous indention "could potentially" be used |
| 407 | as a form of DoS, the option *might* be subject to later removal from HTTP |
| 408 | mode (in CLI it's fine). |
| 409 | |
| 410 | In HTTP mode no trailing newline is added to the output, whereas in CLI |
| 411 | mode one is normally appended (exception: in JSONP mode no newline is |
| 412 | appended, to (rather pedantically and arbitraily) allow the client to |
| @@ -482,11 +482,11 @@ | |
| 482 | normally want to see very specific error codes when tracking down a |
| 483 | problem. We can offer a configuration option to "dumb down" error |
| 484 | codes to their generic category by simply doing a modulo 100 |
| 485 | (or 1000) against the native error code number. e.g. FOSSIL-1271 |
| 486 | could (via a simple modulo) be reduced to FOSSIL-1200 or |
| 487 | FOSSIL-1000, depending on the paranoia level of the sysadmin. I have |
| 488 | tried to order the result code numbers so that a dumb-down level of |
| 489 | 2 provides reasonably usable results without giving away too much |
| 490 | detail to malicious clients.\ |
| 491 | (**TODO:** `g.json.errorDetailParanoia` is used to set the |
| 492 | default dumb-down level, but it is currently set at compile-time. |
| @@ -533,11 +533,11 @@ | |
| 533 | can actually implement this one, though.) |
| 534 | - `FOSSIL-1106`: Assertion failed (or would have had we |
| 535 | continued). Note: if an `assert()` fails in CGI/server modes, the HTTP |
| 536 | response will be code 500 (Internal Server Error). We want to avoid |
| 537 | that and return a JSON response instead. All of that said - there seems |
| 538 | to be little reason to implement this, since assertions are "truly |
| 539 | serious" errors. |
| 540 | - `FOSSIL-1107`: Allocation/out of memory error. This cannot be reasonably |
| 541 | reported because fossil aborts if an allocation fails. |
| 542 | - `FOSSIL-1108`: Requested API is not yet implemented. |
| 543 | - `FOSSIL-1109`: Panic! Fossil's `fossil_panic()` or `cgi_panic()` was |
| 544 |