tiddlyweb http api explorer
chris...@gmail.com
I've made a dynamic API explorer for tiddlyweb:
http://tiddlyweb.tiddlyspace.com/explorer
It's not entirely finished, but it's intent is to make it clear that
there is an API that's available and link it up to documentation.
Please give it a shot and point out any issues.
The code lives here:
https://github.com/cdent/twexplorer
Thanks
--
Chris Dent http://burningchrome.com/
[...]
chris...@gmail.com
> It's not entirely finished, but it's intent is to make it clear that
> there is an API that's available and link it up to documentation.
By the way: I'm making a new stab at migrating, and improving in the
process, the documentation from http://tiddlyweb.peermore.com/ to
http://tiddlyweb.tiddlyspace.com/ .
If you are interested in helping out, it would be very much
appreciated. Just let me know your particular area of interest and
your tiddlyspace username and I can make you an editor.
Eric Drechsel
repositories where the topic meandered to TiddlyWeb - this would be
great for demoing the API during a talk, since it gives interested
folks a jumping off point for further experimentation.
Eric Drechsel
chris...@gmail.com
> Wow, this is phenomenal I've given several talks on personal content
> repositories where the topic meandered to TiddlyWeb - this would be
> great for demoing the API during a talk, since it gives interested
> folks a jumping off point for further experimentation.
Excellent, I'm glad it seems useful. I'd be curious to hear more about
these personal content repos. That's what I was working on before I
started with TiddlyWeb. Something I was calling closet.
All the same functionality is in TiddlyWeb, but now the resources are
called tiddlers.
chris...@gmail.com
> i would be interested in helping out, as a way to get involved in shared
> content creation activities on tiddlyspace and to get more familiar with
> the HTTP APIs myself. My TS username is eric.
Awesome, I'll add you after I fix a bug in /_space that just showed
up.
I'll also write up some meta info about some of the structuring of the
docs and the goals thereof. The explorer thing takes advantage of some
of that structure to do its thing.
Thanks for the offer to participate, it helps a _huge_ amount to keep
me motivated and focused.
Eric Drechsel
FND
> basically would like to use tiddlyweb the server but throw out the
> wiki markup from tiddlywiki in preference for something else, or more
> likely support for a variety of markups.
This is already possible, via the `type` attribute. I've been writing
all my tiddlers in Markdown for ages, e.g.
http://fnd.tiddlyspace.com/Why%20Flask.txt
Chris's recent @edit application lets you choose the format when you
create/modify a tiddler:
http://edit.tiddlyspace.com/edit
-- F.
chris...@gmail.com
> yes, I think tiddlyweb is a great fit for building a place to keep your
> stuff. It's mostly an API, so you can pretty much build any kind of
> client/UX you like on it. The only place where I think it falls down is in
> the tiddler format. I basically would like to use tiddlyweb the server but
> throw out the wiki markup from tiddlywiki in preference for something else,
> or more likely support for a variety of markups. The metadata part of the
> tiddler format is ok, except that it might be nice if you could have
> metadata on binary tiddlers too. Speaking of which, does TiddlyWeb
> currently handle large binary uploads well (ie, not as blobs in SQL)?
As FND points out that the tiddler.text is treated as tiddlywiki
text is just a default. A tidder can have a type (based on
MIME-type) that places it in different categories:
1. The default, which variously shows up as not-set, the value None,
or the string "None" (this complexity is known bug).
2. A mime-type that the rendering subsystem knows about.
(renderable)
3. A mime-type that is not renderable but is considered text
(text/*, application/json, various XML thingies). (psuedo-binary)
4. Anything else, considered binary. These are images, tar files,
document formats that are unlucky enough to not be text.
There are different sections in the code where a tiddler's type
determines how it is going to be treated.
If a tiddler is requested as */* or text/html and is renderable, then it
is given to the rendering subsystem which renders wikitext (or similar)
to HTML. The is a configurable default (tiddlywikitext) and a list of
mime-type to rendering tool mappings. In addition to tiddlywikitext
there are renderers for Markdown and Creole, at least.
If a tiddler is requested as JSON, the value of the text field is
dependent on whether the tiddler in binary or not. If it is binary
then the content is base64 encoded.
You can achieve binary+metadata by either of the following:
* get the tiddler as JSON, based64 decode the text, and process the
metadata
* get the tiddler as JSON with query parameter fat=0 _and_ get the
tiddler as */* (in which case you get the raw binary stream)
If a tiddler considered binary is PUT, then how it is stored is
dependent on the store being used. The default text store does a
base64 encode and writes to disk with the text serialization. The
sqlalchemy based stores do something similar.
As you point out this is not ideal but hasn't presented enough of a
problem to be worth fixing yet. If it were to be fixed I would think
a reference to a binary store would be left in the RDBMS when doing
a put and resolved when doing a get.
There are also efficiency problems with the actual delivery of
binary content to or from the client that could be improved. But
again, thus far it has not presented enough of a problem to devote
effort to it.
So, anyway, basically TiddlyWeb will do what you describe with a bit
of tweaking.
cdent
On Wednesday, April 4, 2012 1:56:27 PM UTC+1, cdent wrote:
On Tue, 3 Apr 2012, Eric Drechsel wrote:> i would be interested in helping out, as a way to get involved in shared
> content creation activities on tiddlyspace and to get more familiar with
> the HTTP APIs myself. My TS username is eric.Awesome, I'll add you after I fix a bug in /_space that just showed
up.
cdent
On Thursday, April 5, 2012 2:23:03 PM UTC+1, cdent wrote:
Haven't gotten around to the meta-doc on the docs yet, but soon.
Eric Drechsel
Eric Drechsel
chris...@gmail.com
> The API explorer only supports GET for interaction currently right?
Yes. I intended to make it do it all but I ran into some barriers:
* interfaces to construct useful PUT data
* security handling so random important stuff didn't get DELETEd
> I'd love to be able to include it in my space with support for PUT, DELETE,
> etc. As a way to experiment with the HTTP API.
>
> Would it be viable to package it up as an includeable app, given that it
> uses documentation from the tiddlyweb space? I guess one could just include
> the whole tiddlyweb space.
I ought to be able to extract it to its own space, and still be able
to acess the docs (since that information is accessed only via GET,
ControlView can be circumvented easily). I'm in a thing called a
"hothouse" for the next two days so it won't happen this week, but it
is doable.
I wrote the thing outside of tiddlyspace, so it ought to still work if you
copy explorer and explorer.js to your own space in the meantime.
It should still "see" the docs correctly.
chris...@gmail.com
> Closet sounds like Locker [1], is that a coincidence? Locker has a very
> interesting SOA that should make it possible to integrate with just about
> anything. Those guys were in Portland last July for OSCON and I
> participated in a bug triage on it but haven't been tracking it since. It
> seems like it's architected to be a content "sink", just aggregating and
> normalizing from primary sources, but maybe that will change.
Closet predates locker by several years, and had a different
orientation. Whereas locker provides access to stuff you have in many
services via connectors, the closet idea was that you put anything in
it, and it provides an opaque URI that is given to a service.
It's one of the conceptual underpinnings of the IBOC concept:
Of course in the last few months the locker guys have lit up nice and
shiny and want to de-emphasize the connectors in favor of peer to peer
distribution and discovery of "stuff" with telehash[1]. All of which
sounds quite awesome.
Closet originally came out of an idea that never got legs at
Socialtext: Building an extremely abstract storage layer that was
purely URI (and content negotiation) driven. The desire for that was
driven by the Socialtext REST API, which was in many ways the
precursor to TiddlyWeb's API. I've wanted to make a Closet store for
TiddlyWeb but there's not really much of a point, because TiddlyWeb is
an arbitrary content store itself...