Fossil SCM

fossil-scm / www / json-api / tips.md

Source Blame History 102 lines

6b17866…	stephan	1	# JSON API: Tips and Tricks
6b17866…	stephan	2	([⬑JSON API Index](index.md))
6b17866…	stephan	3
6b17866…	stephan	4	Jump to:
6b17866…	stephan	5
6b17866…	stephan	6	* [Beware of Content-Type and Encoding...](#content-type)
946bb7e…	stephan	7	* [Using `curl` and `wget`](#curl-wget)
6b17866…	stephan	8	* [Example JavaScript](#javascript)
6b17866…	stephan	9	* [Demo Apps](#demo-apps)
6b17866…	stephan	10
6b17866…	stephan	11	---
6b17866…	stephan	12
6b17866…	stephan	13	<a id="content-type"></a>
6b17866…	stephan	14	# Beware of Content-Type and Encoding...
6b17866…	stephan	15
6b17866…	stephan	16	When posting data to fossil, make sure that the request sends:
6b17866…	stephan	17
946bb7e…	stephan	18	- Content-Type of `application/json`. Fossil also (currently)
6b17866…	stephan	19	accepts `application/javascript` and `text/plain` as JSON input,
6b17866…	stephan	20	but `application/json` is preferred. The client may optionally
6b17866…	stephan	21	send `;charset=utf-8` with the Content-Type, but any other
6b17866…	stephan	22	encoding produces undefined results. Behaviour without the charset
6b17866…	stephan	23	or with `;charset=utf-8` suffix is identical.
6b17866…	stephan	24	- POST data must be an non-form-encoded JSON string
6b17866…	stephan	25	(ASCII or UTF-8). jQuery, by default, form-urlencodes it, which the
6b17866…	stephan	26	fossil json bits cannot read. e.g. post the result of
6b17866…	stephan	27	`JSON.stringify(requestObject)`, without any additional encoding on
6b17866…	stephan	28	top of it.
6b17866…	stephan	29	- When POSTing via jQuery, set these AJAX options:
6b17866…	stephan	30	- `contentType:'application/json'`
6b17866…	stephan	31	- `dataType:'text'`
6b17866…	stephan	32	- `data:JSON.stringify(requestObject)`
6b17866…	stephan	33	- When POSTing via XMLHttpRequest (XHR), be sure to:
6b17866…	stephan	34	- `xhr.open( … )`
6b17866…	stephan	35	- `xhr.setRequestHeader("Content-Type", "application/json")`
6b17866…	stephan	36	- `xhr.send( JSON.stringify( requestObject ) )`
6b17866…	stephan	37
6b17866…	stephan	38	The response will be (except in the case of an HTTP 500 error or
6b17866…	stephan	39	similar) a JSON or JSONP string, ready to be parsed by your favourite
6b17866…	stephan	40	`JSON.parse()` implementation or `eval()`'d directly.
6b17866…	stephan	41
946bb7e…	stephan	42	<a id="curl-wget"></a>
946bb7e…	stephan	43	## Using `curl` and `wget`
946bb7e…	stephan	44
946bb7e…	stephan	45	Both [curl](https://curl.haxx.se/) and
946bb7e…	stephan	46	[wget](https://www.gnu.org/software/wget/) can be used to post data to
946bb7e…	stephan	47	this API from the command line or scripts, but both require an extra
946bb7e…	stephan	48	parameter to set the request encoding.
946bb7e…	stephan	49
946bb7e…	stephan	50	Example:
946bb7e…	stephan	51
946bb7e…	stephan	52	```console
946bb7e…	stephan	53	$ cat x.json
946bb7e…	stephan	54	{
946bb7e…	stephan	55	"payload": {
946bb7e…	stephan	56	"sql": "SELECT * FROM reportfmt limit 1",
946bb7e…	stephan	57	"format": "o"
946bb7e…	stephan	58	}
946bb7e…	stephan	59	}
946bb7e…	stephan	60
946bb7e…	stephan	61	# Fossil has been started locally with:
946bb7e…	stephan	62	# fossil server --localauth
946bb7e…	stephan	63	# which allows the following requests to work without extra
946bb7e…	stephan	64	# authenticaion:
946bb7e…	stephan	65
946bb7e…	stephan	66	$ wget -q -O- \
946bb7e…	stephan	67	--post-file=x.json \
946bb7e…	stephan	68	--header="Content-Type: application/json" \
946bb7e…	stephan	69	'http://localhost:8080/json/query'
946bb7e…	stephan	70
946bb7e…	stephan	71	$ curl \
946bb7e…	stephan	72	--data-binary @x.json \
946bb7e…	stephan	73	--header 'Content-Type: application/json' \
946bb7e…	stephan	74	'http://localhost:8080/json/query'
946bb7e…	stephan	75	```
946bb7e…	stephan	76
946bb7e…	stephan	77	The relevant parts for encoding are the `--header` flag for `wget` and
946bb7e…	stephan	78	`curl`, noting that they have different syntaxes for each
946bb7e…	stephan	79	(`--header=X` vs `--header X`).
946bb7e…	stephan	80
946bb7e…	stephan	81	<a id="javascript"></a>
6b17866…	stephan	82	# Example JavaScript (Browser and Shell)
6b17866…	stephan	83
6b17866…	stephan	84	In the fossil source tree, [in the ajax directory](/dir/ajax), is test/demo code
6b17866…	stephan	85	implemented in HTML+JavaScript. While it is still quite experimental, it
6b17866…	stephan	86	demonstrates one approach to creating client-side wrapper APIs for
6b17866…	stephan	87	remote Fossil/JSON repositories.
6b17866…	stephan	88
6b17866…	stephan	89	There is some additional JS test code, which uses the Rhino JS engine
6b17866…	stephan	90	(i.e. from the console, not the browser), under
6b17866…	stephan	91	[`ajax/i-test`](/dir/ajax/-itest). That adds a Rhino-based connection
6b17866…	stephan	92	back-end to the AJAJ API and uses it for running integration-style
6b17866…	stephan	93	tests against an arbitrary JSON-capable repository.
6b17866…	stephan	94
6b17866…	stephan	95
6b17866…	stephan	96	<a id="demo-apps"></a>
6b17866…	stephan	97	# Demo Apps
6b17866…	stephan	98
6b17866…	stephan	99	Known in-the-wild apps using this API:
6b17866…	stephan	100
6b17866…	stephan	101	- The wiki browsers/editors at [](https://fossil.wanderinghorse.net/wikis/)
6b17866…	stephan	102

Fossil SCM

Keyboard Shortcuts