Janne Jalkanen wrote:
[...]
Also, this relates a bit to our external API thinking: currently, we
support XML-RPC, but that's a fairly old and clunky API. I would
definitely like to support a REST-like interface, but it needs a bit
more thinking. Considering that there's probably going to be quite a
bit of overlap between our JSON APIs, our XML-RPC APIs and our REST
APIs, it might make sense to collapse them into one - like just sticking
to sending JSON back and forth.
There is some advantage in sending also JSON down the line - the format
is simple and expressive, and allows you to get an object you received,
modify it, and return it. So we might consider 3 as a future option.
Or RFC 5023 with extensions.
I know I've not been very active on this project lately, we've had some
management hitches at this end that have kept me busy on other projects
and the previous development of the assertion framework is currently on
hold. That said, we just launched a new internal enterprise wiki and I've
still be quite actively using JSPWiki and developing associated tools,
though currently most of that is on internal products.
One project I've got mostly working is a wiki chat feature that uses an
external web service for storage. The web service was actually developed
for a different project but the URL scheme was suitable. There were three
options available in design/configuration, to avoid browser cross-site
security issues:
1. have the web service embedded in the wiki itself
2. use the wiki as a pipe to the web service (performance bottleneck?)
3. uses subdomain aliasing to have both the wiki and the web
service at the same subdomain and port (i.e., differentiate
at the web application level, e.g., webapps/wiki/ and webapps/ws/)
Option 3 is what we're currently doing.
In doing a lot of thinking about REST-style web services (as part of a
different project), I'm almost at a point where I think the entire URI
scheme for the wiki should be handled in this manner -- we could rid
ourselves of all the various URL constructors (though I suppose we might
have to deal with backwards-compatibility issues for existing wikis) and
have a nice clean URL scheme.
The basic scheme I've ended up with has a fixed number of path components,
the last one being the action or verb. Optionally appended to this would
be any query features, considered as parameters. But the basic URL (and
the web service itself) would function without query parameters.
For example, where 'f' is format:
http://acme.com/wiki/pages/PageName/get default output (XHTML)
http://acme.com/wiki/pages/PageName/get?f=text text output
http://acme.com/wiki/pages/PageName/get?f=json JSON output
An idea derived from the ARK specification, doubling up on the
question marks returns page metadata:
http://acme.com/wiki/pages/PageName/get?? return page metadata
Whether this survives the final design is as yet unknown.
The current set of actions includes:
get return record (page) content
pid return persistent identifier
key return public key (securely ties web service to JSP)
terms return all record (page) metadata
term return a single metadata term (uses query parameter for name)
index return index of records (pages)
post post new record (page)
make tinyurl-like redirect service
put modify existing record (page)
delete delete record (page)
query query database for records (pages)
admin admin functions
ingest ingest bulk records (pages)
help return API help
test run unit tests, returning result
The primary function of the web service project is a persistent identifier
service, but we ended up using its storage features for the wiki chat
feature. I'm not sure if this is of any interest or relevance but I
thought to pass it along.
Murray
...........................................................................
Murray Altheim <murray09 at altheim dot com> === = =
http://www.altheim.com/murray/ = = ===
SGML Grease Monkey, Banjo Player, Wantanabe Zen Monk = = = =
Boundless wind and moon - the eye within eyes,
Inexhaustible heaven and earth - the light beyond light,
The willow dark, the flower bright - ten thousand houses,
Knock at any door - there's one who will respond.
-- The Blue Cliff Record
