47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
|
Certain requests, mainly things like editing checkin messages and
committing new files entirely, require POST data. This is fundamentally
very simple to do - clients post plain/unencoded JSON using a common
wrapper envelope which contains the request-specific data to submit as
well as some request-independent information (like authentication data).
## POST Request Envelope
POST requests are sent to the same URL as their GET counterpart (if any,
else their own path), and are sent as plain-text/unencoded JSON wrapped
in a common request envelope with the following properties:
|
>
<
|
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
|
Certain requests, mainly things like editing checkin messages and
committing new files entirely, require POST data. This is fundamentally
very simple to do - clients post plain/unencoded JSON using a common
wrapper envelope which contains the request-specific data to submit as
well as some request-independent information (like authentication data).
<a id="request-envelope"></a>
## POST Request Envelope
POST requests are sent to the same URL as their GET counterpart (if any,
else their own path), and are sent as plain-text/unencoded JSON wrapped
in a common request envelope with the following properties:
(TODO: convert to a simple list...)
```
+-----------------------------------+-----------------------------------+
| requestId | Optional arbitrary JSON value, |
| | not used by fossil, but returned |
| | as-is in responses. |
|
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
uses 1 cookie (the login token), and i'd prefer to keep it that way.)
POST requests without such an envelope will be rejected, generating a
Fossil/JSON error response (as opposed to an HTTP error response). GET
requests, by definition, never have an envelope.
POSTed client requests *must* send a Content-Type header of either
application/json , application/javascript, or text/plain, or the
JSON-handling code will never see the POST data. The POST handler
optimistically assumes that type text/plain "might be JSON", since
application/json is a newer convention which many existing clients do
not use.
## POST Envelope vs. `POST.payload`
When this document refers to POST data, it is referring to top-level
object in JSON-format POSTed input data. When we say `POST.payload` we
refer to the "payload" property of the POST data. While fossil's core
|
|
|
|
|
|
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
uses 1 cookie (the login token), and i'd prefer to keep it that way.)
POST requests without such an envelope will be rejected, generating a
Fossil/JSON error response (as opposed to an HTTP error response). GET
requests, by definition, never have an envelope.
POSTed client requests *must* send a Content-Type header of either
`application/json` , `application/javascript`, or `text/plain`, or the
JSON-handling code will never see the POST data. The POST handler
optimistically assumes that type `text/plain` "might be JSON", since
`application/json` is a newer convention which many existing clients
do not use (as of the time these docs were written, back in 2011).
## POST Envelope vs. `POST.payload`
When this document refers to POST data, it is referring to top-level
object in JSON-format POSTed input data. When we say `POST.payload` we
refer to the "payload" property of the POST data. While fossil's core
|
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
|
Apropos UTF-8: note that JSON is, by definition, Unicode and recommends
UTF-8 encoding (which is what we use). That means if your console cannot
handle UTF-8 then using this API in CLI mode might (depending on the
content) render garbage on your screen.
<a href="cli-vs-http"></a>
# CLI vs. HTTP Mode
CLI (command-line interface) and HTTP modes (CGI and standalone server)
are consolidated in the same implementations and behave essentially
identically, with only minor exceptions.
An HTTP path of `/json/foo` translates to the CLI command `fossil json
|
|
|
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
|
Apropos UTF-8: note that JSON is, by definition, Unicode and recommends
UTF-8 encoding (which is what we use). That means if your console cannot
handle UTF-8 then using this API in CLI mode might (depending on the
content) render garbage on your screen.
<a id="cli-vs-http"></a>
# CLI vs. HTTP Mode
CLI (command-line interface) and HTTP modes (CGI and standalone server)
are consolidated in the same implementations and behave essentially
identically, with only minor exceptions.
An HTTP path of `/json/foo` translates to the CLI command `fossil json
|