JSON Keys protocol
We can think of a website as an asynchronous tree whose values can be retrieved via HTTP/S requests. Sadly, HTTP does not provide a way to list the keys of a subtree, so normally it is impossible to completely traverse a site’s tree.
To remedy that, a site can indicate which keys are available at a given route by supporting the JSON Keys protocol:
- Every route can expose its keys by defining a
.keys.json
file. - This contains an array in JSON format of the keys available at that route.
- If a key represents a subtree, the key end in a trailing
/
slash, although that is not required.
This Web Origami site supports this JSON Keys protocol. For example, it has a route /samples/greetings
containing some trivial files like /samples/greetings/Alice. The server defines a JSON file at /samples/greetings/.keys.json that enumerates the names of those files:
["Alice", "Bob", "Carol"]
The higher level route /samples
likewise has a /samples/.keys.json file listing its keys, including the greetings/
key:
[
"greetings/",
... other keys ...
]
The information makes a site tree traversable. The underlying SiteTree
class supports the JSON Keys protocol. If you ask a SiteTree
for its keys, it will retrieve this .keys.json
file and, if found, return those keys. (It will strip the trailing /
from any keys for subtrees.)
For example, you can use the ori CLI to display the keys of a given site route using the custom tree or treehttp protocols:
$ ori @keys tree://weborigami.org/samples/greetings/
- Alice
- Bob
- Carol
You can also use ori to display the complete contents of all pages at a given route:
$ ori tree://weborigami.org/samples/greetings/
Alice: Hello, Alice.
Bob: Hello, Bob.
Carol: Hello, Carol.
Above, the custom tree:
protocol retrieves the route’s keys defined in the .keys.json
, then makes separate requests for each of those pages.
The .keys.json
file should normally not include itself in its list of keys.
Adding support for JSON Keys to your site
The Origami builtin @jsonKeys function makes it easy to define .keys.json
files for all routes in a given tree.
Given the very basic nature of the protocol, it is not hard to implement in other systems. Example: an implementation of JSON Keys for Apache and PHP.
SiteTree class
SiteTree([href]) constructor
- href: string
resolve(path)
- path: string
Returns: SiteTree
Returns a new SiteTree
for the given relative route.