-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
258 lines (237 loc) · 12.1 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>JSON->URL</title>
<meta name="description" content=
"JSON->URL defines a text format for the JSON data model suitable for use within a URL or URI.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="jsonurl">
<meta property="og:locale" content="en_US">
<meta property="og:image" content="img/logo.jpg">
<meta property="og:title" content="JSON inside a URL">
<meta property="og:description" content=
"JSON->URL defines a text format for the JSON data model suitable for use within a URL or URI.">
<link rel="apple-touch-icon" type="image/png" sizes="180x180" href="img/apple-touch-icon.png">
<link rel="icon" type="image/png" href="img/android-chrome-192x192.png" sizes="192x192" />
<link rel="icon" type="image/png" href="img/favicon-32x32.png" sizes="32x32" />
<link rel="icon" type="image/png" href="img/favicon-16x16.png" sizes="16x16" />
<link rel="shortcut icon" href="img/favicon.ico">
<link rel="canonical" href="https://www.jsonurl.org/">
<link rel="image_src" type="image/png" href="img/android-chrome-512x512.png">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/kognise/water.css@latest/dist/light.min.css">
<link rel="stylesheet" href="jsonurl.css">
</head>
<body>
<header>
<h1><a href="/" name="top"><img alt="JSON→URL" src="img/logo.png"></a></h1>
<nav role="navigation">
<ul>
<li><a href="#about">About</a></li>
<li><a href="#code">Code</a></li>
<li><a href="#examples" class="sandbox-link">Examples</a></li>
<li><a href="#basics">Basics</a></li>
<li><a href="#spec">Specification</a></li>
<li><a href="#relatedwork">Related Work</a></li>
</ul>
</nav>
</header>
<main>
<section>
<h2><a name="about" href="#about">About</a></h2>
<p><a href="https://tools.ietf.org/html/rfc8259">RFC8259</a> describes the
JSON data model and interchange format, which is
widely used in
<a href="https://en.wikipedia.org/wiki/Application_layer">application-level</a>
protocols including
<a href="https://en.wikipedia.org/wiki/Representational_state_transfer">RESTful</a>
<a href="https://en.wikipedia.org/wiki/Web_API">API</a>s. It is
common for applications to request resources via the
<a href="https://en.wikipedia.org/wiki/POST_(HTTP)">HTTP POST</a> method,
with JSON
<a href="https://tools.ietf.org/html/rfc2068#section-7">entities</a>.
However, POST is suboptimal for requests which do not modify a
<a href="https://tools.ietf.org/html/rfc7231#section-2">resource</a>'s
state. JSON→URL defines a text format for the JSON
data model suitable for use within a
<a href="https://tools.ietf.org/html/rfc1738">URL</a>/<a
href="https://tools.ietf.org/html/rfc3986">URI</a>.</p>
</section>
<section>
<h2><a name="code" href="#code">Code</a></h2>
<p>JSON→URL is language agnostic. A formal specification defines
the grammar, and class/function libraries implement an idiomatic
interface.
<ul>
<li>jsonurl-java - Java implementation
(<a href="https://github.com/jsonurl/jsonurl-java"
title="jsonurl-java GitHub repository"
data-goal="link-github-jsonurl-java">GitHub</a>,
<a href="https://mvnrepository.com/artifact/org.jsonurl"
title="jsonurl-java Maven artifact"
data-goal="link-maven-jsonurl-java">Maven</a>)
<li>jsonurl-js - JavaScript implementation
(<a href="https://github.com/jsonurl/jsonurl-js"
title="jsonurl-js GitHub repository"
data-goal="link-github-jsonurl-js">GitHub</a>,
<a href="https://www.npmjs.com/package/@jsonurl/jsonurl"
title="jsonurl-js NPM artifact"
data-goal="link-npm-jsonurl-js">NPM</a>,
<a href="https://libraries.io/npm/@jsonurl%2Fjsonurl"
title="jsonurl-js libraries.io listing"
data-goal="link-libraries-jsonurl-js">libraries.io</a>)
<li>jsonurl-py - Python implementation
(<a href="https://github.com/cdleonard/jsonurl-py"
title="jsonurl-py GitHub repository"
data-goal="link-github-jsonurl-py">GitHub</a>,
<a href="https://pypi.org/project/jsonurl-py/0.4.0/"
title="jsonurl-py PyPI artifact"
data-goal="link-pypi-jsonurl-py">PyPI</a>,
<a href="https://libraries.io/pypi/jsonurl-py"
title="jsonurl-py libraries.io listing"
data-goal="link-libraries-jsonurl-py">libraries.io</a>)
</ul>
</section>
<section id="sandbox">
<h2><a name="examples" href="#examples">Examples</a></h2>
<table>
<caption>A picture is worth 1e3 words</caption>
<thead><tr><th>JSON</th><th>JSON→URL</th></tr></thead>
<tbody>
<tr><td>true</td><td>true</td></tr>
<tr><td>false</td><td>false</td></tr>
<tr><td>null</td><td>null</td></tr>
<tr><td>{"Hello":"World!"}</td><td>(Hello:World!)</td></tr>
<tr><td>[1,2.0,-3e7]</td><td>(1,2.0,-3e7)</td></tr>
<tr><td>{"key":"value","nested":["array","of","strings"]}</td>
<td>(key:value,nested:(array,of,strings))</td></tr>
<tr><td>"Ben & Jerry's"</td><td>Ben+%26+Jerry's</td></tr>
<tr><td>"true"</td><td>'true'</td></tr>
</tbody>
</table>
</section>
<section>
<h2><a name="basics" href="#basics">Basic Rules</a></h2>
<p>The primary goal of JSON→URL is to make the resulting
URL readable — or at least as readable as possible — and
therefore meaningful to the user.
<p>The spec outlines the complete grammar, but the basic
concept can be understood by applying the following rules to
JSON text.
<ul>
<li>JSON→URL text is limited to a subset of the characters allowed
in a URL
<a href="https://tools.ietf.org/html/rfc3986#section-3.4">query string</a>.
All other characers must be
<a href="https://en.wikipedia.org/wiki/Percent-encoding">percent encoded</a>.
<li>The <code>[</code>, <code>]</code>, <code>{</code>, and
<code>}</code> characters are not allowed in a URL query string so
objects and arrays both begin with <code>(</code> and end with
<code>)</code>.
<li>The <kbd>true</kbd>, <kbd>false</kbd>, <kbd>null</kbd>, and number
literals look exactly like they do in JSON.
<li>A string literal is quoted between two <code>'</code> characters,
because <code>"</code> is not allowed in a URL query string. A string only
needs to be quoted if it is <kbd>true</kbd>, <kbd>false</kbd>,
<kbd>null</kbd>, or looks like a number.
<li>Literal whitespace is not allowed in a URL query string. A single
space may be encoded with a <code>+</code> character. Spaces may only
appear where a string literal is allowed, and they are always meaningful.
</ul>
<h3><a name="aqf" href="#aqf">Browser Address Bar</a></h3>
<p>Special consideration should be taken when using JSON→URL in
a browser address bar. Some browsers may change <code>'</code> to
<code>%x27</code>, which interferes with the string literal
syntax described above. To sidestep this problem JSON→URL can
optionally use escape sequences in string literals, rather than relying
on quotes and encoding. An escape sequence begins with <code>!</code>,
because <code>\</code> is not allowed in a URL query string.</p>
</section>
<section>
<h2><a name="spec" href="#spec">Specification</a></h2>
<p>The <a href="https://github.com/jsonurl/specification/">JSON→URL
specification</a> defines the complete grammar.</p>
</section>
<section>
<h2><a name="relatedwork" href="#relatedwork">Related Work</a></h2>
<p>The following libraries (written by others) provide similar or related functionality.
<dl>
<dt><a href="https://github.com/Sage/jsurl">jsurl</a></dt>
<dd>A JavaScript library similar in goal to JSON→URL. It
uses tilde as an escape sequence for literals and to
differentiate between open object and open array.</dd>
<dt><a href="https://www.npmjs.com/package/json-url">json-url</a></dt>
<dd>A JavaScript library to serialize/deserialize arbitrary JSON text
to/from a clob suitable for use in a URL query string. The primary
goal is to optimize for size rather than readability. It offers
several compression options and looks quite complete.</dd>
<dt><a href="https://github.com/TimoBechtel/json2url#readme">json2url</a></dt>
<dd>A JavaScript library for encoding and decoding JavaScript objects to/from a URL
compatible string. The format appears to be compatible with classic
<abbr>CGI</abbr> query strings (i.e. x-www-form-unlencoded).</dd>
<dt><a href="https://github.com/CottageLabs/jsonurl#readme">jsonurl</a></dt>
<dd>A Python library for serializing and deserializing Python data structures
to/from a URL query string.</dd>
<dt><a href="https://github.com/KilledByAPixel/JSONCrush#readme">JSONCrush</a></dt>
<dd>A JavaScript library for compressing URI encoded JSON text.</dd>
<dt>Rison</dt>
<dd>A specification similar in goal to JSON→URL. The original
website is defunct, however, an archived copy is available via <a
href="https://web.archive.org/web/20130910064110/http://www.mjtemplate.org/examples/rison.html"
>archive.org</a>. The original JavaScript implementation is no longer
maintained, however, there are
<a href="https://github.com/Nanonid/rison">some</a>
<a href="https://github.com/w33ble/rison-node">forks</a>.</dd>
<dt><a href="https://github.com/pieroxy/lz-string#readme">lz-string</a></dt>
<dd>A JavaScript library for compressing <i>any</i> content using an
<a href="https://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Welch">LZ</a>-based
approach. The result can be <a href="https://en.wikipedia.org/wiki/Base64">base64</a>
encoded, which is then <a href="https://en.wikipedia.org/wiki/Base64#URL_applications"
>safe</a> to store in a URL.</dd>
</dl>
</section>
<footer>
<a name="footer"></a><hr>
<form id="vote" autocomplete="off" novalidate>
<span>This webpage is good:</span>
<span>
<input type="radio" name="vote" value="yes"
id="vote-landing-good"
data-goal="vote-landing-good"
data-thumb="👍">
<label for="vote-landing-good">Yes</label>
</span>
<span>
<input type="radio" name="vote" value="no"
id="vote-landing-bad"
data-goal="vote-landing-bad"
data-thumb="👎">
<label for="vote-landing-bad">No</label>
</span>
</form>
<span>
<a title="Privacy Policy" href="privacy">Privacy Policy</a>
<a title="GitHub" href="https://github.com/jsonurl">GitHub</a>
<a title="Continuous Deployment" href="https://netlify.com/">Netlify</a>
</span>
</footer>
</main>
<script
src="https://cdn.jsdelivr.net/npm/@jsonurl/[email protected]"
integrity="sha512-ZkCdWNHe73NUE5JGh5np0nCwazEu8jRG/bTT24zEeY825xMnhVlwKK29TWyYkvS1vT/gOFJtH4mK1Uns3yW+Wg=="
crossorigin="anonymous"></script>
<script
src="https://cdn.jsdelivr.net/npm/[email protected]"
integrity="sha512-XdUZ5nrNkVySQBnnM5vzDqHai823Spoq1W3pJoQwomQja+o4Nw0Ew1ppxo5bhF2vMug6sfibhKWcNJsG8Vj9tg=="
crossorigin="anonymous"></script>
<script
src="https://cdn.jsdelivr.net/npm/[email protected]"
integrity="sha384-H6KKS1H1WwuERMSm+54dYLzjg0fKqRK5ZRyASdbrI/lwrCc6bXEmtGYr5SwvP1pZ"
crossorigin="anonymous"></script>
<script
src="sandbox.js"
crossorigin="anonymous"></script>
<!-- touch -->
</body>
</html>