Fossil SCM
Folded info about binary data, 64-bit ints, and timestamp values from [forum:/forumpost/819f1ddbb6 | a recent forum sub-thread] into the JSON API intro doc.
Commit
0f20b5379414a2dc2fd380579d5a5415fa93f7965b25436cad4c264459a40b88
Parent
34205ea468e4fb4…
1 file changed
+28
-32
+28
-32
| --- www/json-api/intro.md | ||
| +++ www/json-api/intro.md | ||
| @@ -140,42 +140,38 @@ | ||
| 140 | 140 | # Technical Problems and Considerations |
| 141 | 141 | |
| 142 | 142 | A random list of considerations which need to be made and potential |
| 143 | 143 | problem areas... |
| 144 | 144 | |
| 145 | -- **Binary data:** HTML4 and JavaScript have no portable way of | |
| 146 | - handling binary data, so commands which could potentially deal with | |
| 147 | - binary data (e.g. committing a file) are ruled out for the time | |
| 148 | - being. HTML5 and accompanying JavaScript additions will binary | |
| 149 | - data usable client-side. That said, a JSON interface cannot natively | |
| 150 | - work with binary unless it is encoded (base64 or hex or whatever), | |
| 151 | - and such encoding would have to be understood on both the server and | |
| 152 | - client sides, which may rule out usage in some environments.\ | |
| 153 | - **Status:** deferred until needed. My current thinking is to send | |
| 154 | - URLs instead of binary data, and the URLs would point to some path | |
| 155 | - which produces the raw artifact content. We could read POSTed binary | |
| 156 | - input, but this might require some re-tooling of fossil's innards | |
| 157 | - and it precludes the use of a JSON request envelope, so it would be | |
| 158 | - limited to requests which can be configured solely via GET arguments | |
| 159 | - (as opposed to POST envelope/payload options). i.e. configure the | |
| 160 | - JSON bits via GET and POST the binary data. | |
| 161 | -- **64-bit integers:** JSON does not specify integer precision, | |
| 162 | - probably because it targets many different platforms and not all | |
| 163 | - of them can support more than 32 bits. JavaScript (from which JSON | |
| 164 | - derives) supports 53 bits of integer precision. That said, it's | |
| 165 | - "highly unlikely" that we'll have any range problems with "only" | |
| 166 | - 53 bits of precision. The underlying JSON API supports *signed* | |
| 167 | - 32- or 64-bit integers on both 32- and 64-bit builds, but only if | |
| 168 | - "long long" or `int64_t` are available (from the C99 header | |
| 169 | - `stdint.h`). Only multi-gig repositories are ever expected to use | |
| 170 | - large numbers, and even then only rarely (e.g. via the "stat" | |
| 171 | - command). | |
| 172 | -- **Timestamps:** for portability this API uses GMT Unix Epoch | |
| 173 | - timestamps. They are the most portable time representation out | |
| 174 | - there, easily usable in most programming environments. (In hindsight, | |
| 175 | - this should have been Unix + Milliseconds, but the API already | |
| 176 | - pervasively uses seconds-precision.) | |
| 145 | +- **Binary data:** JSON is a text serialization method, and it takes | |
| 146 | + up the “payload” area of each HTTP request, so there is no | |
| 147 | + reasonable way to include binary data in the JSON message without | |
| 148 | + some sort of codec like Base64, for which there is no provision in | |
| 149 | + the current JSON API. You will therefore find no JSON API for | |
| 150 | + committing changes to a file in the repository, for example. Other | |
| 151 | + Fossil APIs such as [`/raw`](/help?cmd=/raw) or | |
| 152 | + [`/fileedit`](../fileedit-page.md) may serve you better. | |
| 153 | +- **64-bit integers:** The JSON standard does not specify integer precision, | |
| 154 | + because it targets many different platforms, and not all of | |
| 155 | + them can support more than 32 bits. JavaScript (from which JSON | |
| 156 | + derives) supports 53 bits of integer precision, which may affect how | |
| 157 | + a given client-side JSON implementation sends large integers to Fossil’s JSON | |
| 158 | + API. Our JSON parser can cope with integers larger than 32 bits on input, and it | |
| 159 | + can emit them, but it requires platform support. If you’re running | |
| 160 | + Fossil on a 64-bit host, you should not run into problems in | |
| 161 | + this area, but if you’re on a legacy 32-bit only or a mixed 32/64-bit | |
| 162 | + system, it’s possible that some integers in the API could be | |
| 163 | + clipped. Realize however that this is a rare case: Fossil currently | |
| 164 | + cannot store files large enough to exceed a 32-bit `size_t` value, | |
| 165 | + and `time_t` won’t roll past 32-bit integers until 2038. We’re aware | |
| 166 | + of no other uses of integers in this API that could even in | |
| 167 | + principle exceed the range of a 32-bit integer. | |
| 168 | +- **Timestamps:** For portability, this API uses UTC Unix epoch | |
| 169 | + timestamps. (`time_t`) They are the most portable time representation out | |
| 170 | + there, easily usable in most programming environments. (In | |
| 171 | + hindsight, we might better have used a higher-precision time format, | |
| 172 | + but changing that now would break API compatibility.) | |
| 177 | 173 | - **Artifact vs. Artefact:** both are correct vis-a-vis the |
| 178 | 174 | english language but Fossil consistently uses the former, so we’ll |
| 179 | 175 | use that. |
| 180 | 176 | - **Multiple logins per user:** fossil currently does not allow |
| 181 | 177 | multiple active logins for a given user except anonymous. For all |
| 182 | 178 |
| --- www/json-api/intro.md | |
| +++ www/json-api/intro.md | |
| @@ -140,42 +140,38 @@ | |
| 140 | # Technical Problems and Considerations |
| 141 | |
| 142 | A random list of considerations which need to be made and potential |
| 143 | problem areas... |
| 144 | |
| 145 | - **Binary data:** HTML4 and JavaScript have no portable way of |
| 146 | handling binary data, so commands which could potentially deal with |
| 147 | binary data (e.g. committing a file) are ruled out for the time |
| 148 | being. HTML5 and accompanying JavaScript additions will binary |
| 149 | data usable client-side. That said, a JSON interface cannot natively |
| 150 | work with binary unless it is encoded (base64 or hex or whatever), |
| 151 | and such encoding would have to be understood on both the server and |
| 152 | client sides, which may rule out usage in some environments.\ |
| 153 | **Status:** deferred until needed. My current thinking is to send |
| 154 | URLs instead of binary data, and the URLs would point to some path |
| 155 | which produces the raw artifact content. We could read POSTed binary |
| 156 | input, but this might require some re-tooling of fossil's innards |
| 157 | and it precludes the use of a JSON request envelope, so it would be |
| 158 | limited to requests which can be configured solely via GET arguments |
| 159 | (as opposed to POST envelope/payload options). i.e. configure the |
| 160 | JSON bits via GET and POST the binary data. |
| 161 | - **64-bit integers:** JSON does not specify integer precision, |
| 162 | probably because it targets many different platforms and not all |
| 163 | of them can support more than 32 bits. JavaScript (from which JSON |
| 164 | derives) supports 53 bits of integer precision. That said, it's |
| 165 | "highly unlikely" that we'll have any range problems with "only" |
| 166 | 53 bits of precision. The underlying JSON API supports *signed* |
| 167 | 32- or 64-bit integers on both 32- and 64-bit builds, but only if |
| 168 | "long long" or `int64_t` are available (from the C99 header |
| 169 | `stdint.h`). Only multi-gig repositories are ever expected to use |
| 170 | large numbers, and even then only rarely (e.g. via the "stat" |
| 171 | command). |
| 172 | - **Timestamps:** for portability this API uses GMT Unix Epoch |
| 173 | timestamps. They are the most portable time representation out |
| 174 | there, easily usable in most programming environments. (In hindsight, |
| 175 | this should have been Unix + Milliseconds, but the API already |
| 176 | pervasively uses seconds-precision.) |
| 177 | - **Artifact vs. Artefact:** both are correct vis-a-vis the |
| 178 | english language but Fossil consistently uses the former, so we’ll |
| 179 | use that. |
| 180 | - **Multiple logins per user:** fossil currently does not allow |
| 181 | multiple active logins for a given user except anonymous. For all |
| 182 |
| --- www/json-api/intro.md | |
| +++ www/json-api/intro.md | |
| @@ -140,42 +140,38 @@ | |
| 140 | # Technical Problems and Considerations |
| 141 | |
| 142 | A random list of considerations which need to be made and potential |
| 143 | problem areas... |
| 144 | |
| 145 | - **Binary data:** JSON is a text serialization method, and it takes |
| 146 | up the “payload” area of each HTTP request, so there is no |
| 147 | reasonable way to include binary data in the JSON message without |
| 148 | some sort of codec like Base64, for which there is no provision in |
| 149 | the current JSON API. You will therefore find no JSON API for |
| 150 | committing changes to a file in the repository, for example. Other |
| 151 | Fossil APIs such as [`/raw`](/help?cmd=/raw) or |
| 152 | [`/fileedit`](../fileedit-page.md) may serve you better. |
| 153 | - **64-bit integers:** The JSON standard does not specify integer precision, |
| 154 | because it targets many different platforms, and not all of |
| 155 | them can support more than 32 bits. JavaScript (from which JSON |
| 156 | derives) supports 53 bits of integer precision, which may affect how |
| 157 | a given client-side JSON implementation sends large integers to Fossil’s JSON |
| 158 | API. Our JSON parser can cope with integers larger than 32 bits on input, and it |
| 159 | can emit them, but it requires platform support. If you’re running |
| 160 | Fossil on a 64-bit host, you should not run into problems in |
| 161 | this area, but if you’re on a legacy 32-bit only or a mixed 32/64-bit |
| 162 | system, it’s possible that some integers in the API could be |
| 163 | clipped. Realize however that this is a rare case: Fossil currently |
| 164 | cannot store files large enough to exceed a 32-bit `size_t` value, |
| 165 | and `time_t` won’t roll past 32-bit integers until 2038. We’re aware |
| 166 | of no other uses of integers in this API that could even in |
| 167 | principle exceed the range of a 32-bit integer. |
| 168 | - **Timestamps:** For portability, this API uses UTC Unix epoch |
| 169 | timestamps. (`time_t`) They are the most portable time representation out |
| 170 | there, easily usable in most programming environments. (In |
| 171 | hindsight, we might better have used a higher-precision time format, |
| 172 | but changing that now would break API compatibility.) |
| 173 | - **Artifact vs. Artefact:** both are correct vis-a-vis the |
| 174 | english language but Fossil consistently uses the former, so we’ll |
| 175 | use that. |
| 176 | - **Multiple logins per user:** fossil currently does not allow |
| 177 | multiple active logins for a given user except anonymous. For all |
| 178 |