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