initial commitHEADmaster

1 files changed, 102 insertions, 0 deletions

diff --git a/www/json-api/tips.md b/www/json-api/tips.md
new file mode 100644
index 0000000..885bdf8
--- /dev/null
+++ b/www/json-api/tips.md
@@ -0,0 +1,102 @@
+# JSON API: Tips and Tricks
+([⬑JSON API Index](index.md))
+
+Jump to:
+
+* [Beware of Content-Type and Encoding...](#content-type)
+  * [Using `curl` and `wget`](#curl-wget)
+* [Example JavaScript](#javascript)
+* [Demo Apps](#demo-apps)
+
+---
+
+<a id="content-type"></a>
+# Beware of Content-Type and Encoding...
+
+When posting data to fossil, make sure that the request sends:
+
+-   **Content-Type** of `application/json`. Fossil also (currently)
+    accepts `application/javascript` and `text/plain` as JSON input,
+    but `application/json` is preferred. The client may optionally
+    send `;charset=utf-8` with the Content-Type, but any other
+    encoding produces undefined results. Behaviour without the charset
+    or with `;charset=utf-8` suffix is identical.
+-   **POST data must be an non-form-encoded JSON string**
+    (ASCII or UTF-8). jQuery, by default, form-urlencodes it, which the
+    fossil json bits cannot read. e.g. post the result of
+    `JSON.stringify(requestObject)`, without any additional encoding on
+    top of it.
+-   **When POSTing via jQuery**, set these AJAX options:
+    -   `contentType:'application/json'`
+    -   `dataType:'text'`
+    -   `data:JSON.stringify(requestObject)`
+-   **When POSTing via XMLHttpRequest** (XHR), be sure to:
+    -   `xhr.open( … )`
+    -   `xhr.setRequestHeader("Content-Type", "application/json")`
+    -   `xhr.send( JSON.stringify( requestObject ) )`
+
+The response will be (except in the case of an HTTP 500 error or
+similar) a JSON or JSONP string, ready to be parsed by your favourite
+`JSON.parse()` implementation or `eval()`'d directly.
+
+<a id="curl-wget"></a>
+## Using `curl` and `wget`
+
+Both [curl](https://curl.haxx.se/) and
+[wget](https://www.gnu.org/software/wget/) can be used to post data to
+this API from the command line or scripts, but both require an extra
+parameter to set the request encoding.
+
+Example:
+
+```console
+$ cat x.json
+{
+"payload": {
+  "sql": "SELECT * FROM reportfmt limit 1",
+  "format": "o"
+  }
+}
+
+# Fossil has been started locally with:
+#   fossil server --localauth
+# which allows the following requests to work without extra
+# authenticaion:
+
+$ wget -q -O- \
+  --post-file=x.json \
+  --header="Content-Type: application/json" \
+  'http://localhost:8080/json/query'
+
+$ curl \
+  --data-binary @x.json \
+  --header 'Content-Type: application/json' \
+  'http://localhost:8080/json/query'
+```
+
+The relevant parts for encoding are the `--header` flag for `wget` and
+`curl`, noting that they have different syntaxes for each
+(`--header=X` vs `--header X`).
+
+<a id="javascript"></a>
+# Example JavaScript (Browser and Shell)
+
+In the fossil source tree, [in the ajax directory](/dir/ajax), is test/demo code
+implemented in HTML+JavaScript. While it is still quite experimental, it
+demonstrates one approach to creating client-side wrapper APIs for
+remote Fossil/JSON repositories.
+
+There is some additional JS test code, which uses the Rhino JS engine
+(i.e. from the console, not the browser), under
+[`ajax/i-test`](/dir/ajax/-itest). That adds a Rhino-based connection
+back-end to the AJAJ API and uses it for running integration-style
+tests against an arbitrary JSON-capable repository.
+
+
+<a id="demo-apps"></a>
+# Demo Apps
+
+Known in-the-wild apps using this API:
+
+-   The wiki browsers/editors at [](https://fossil.wanderinghorse.net/wikis/)
+