see http://tiddlyhome.appspot.com/

From: BidiX
Date: Sun, 15 Jun 2008 10:46:54 -0700 (PDT)
Subject: Re: Plugin Library: API concept

Hi FND,

First, I've to say that your post found me in documenting the RESTful API for TiddlyHome 2.0 [1] (For now TiddlyHome 2.0 is a work in progress, a pre-beta version is still available at TiddlyHome.appspot.com/).

For this I implemented an abstract model in Google Apps based on WebApp extension [2]. I'll try to share with you in your Plugin Directory context what I'm experimenting.

So please take this as a constructive contribution.

On Jun 13, 1:34 pm, FND wrote:

> There are two obvious options for accessing that data:
> * a web interface for browsing and searching
> * direct integration with TiddlyWiki (e.g. via the importing wizard)
> No matter which option we choose to implement first, both require an API
> to retrieve the plugins from the database.

You should be more generic. An API is "Programming Interface", the first goal for the API is to be called from whatever application. The browser and the HTML interface is only a limited use of your application. What about an application written in whatever language (python for example) that GET a plugin via a "fetchurl" API to do something (code reformatting, optimization, cooking etc...).

> Here are some early thoughts on that API:
> * REST exposure; everything's accessible via a URL

You need to explain "everything". Resources are referenced by URI. I think you have two resources in your application :
* Plugin: /plugins/
* Repository: /repositories/

may be also Author ?

Your API should also provides functions to create, replace, update, delete a Plugin, a Repository and certainly a Category etc ... For that you should certainly use GET, POST, PUT, DELETE in some way.

> * results might be returned as JSON or pseudo-HTML (TW store format)
> ** returned are complete plugin tiddlers - any further processing should
> be performed client-side ("stupid server")

You should manage different formats (presentation) perhaps as content- type: text/html, text/plain ... Suffix like in TiddlyWeb (.html, .tw, .xml, .js) is certainly a good direction.

> * assuming a base URL likehttp://plugins.tiddlywiki.org/api/...
> ** /titles/%s - returns plugin %s (potential problem: would return more
> than a single item if several plugins carry the same name)
> ** /categories/%s/ - returns all plugins of category %s
> ** /tags/%s/ - returns all plugins carrying the tag(s) %s
> ** /ratings/%s/ - returns all plugins with rating %s
> ** ?%f=%s - filters results by attribute %f (e.g. author) and value %s
> (this might be dropped, as it goes against the stupid-server principle)

You certainly need also to explain some relations between plugin- repository-author like /authors/Eric/categories/Formatting/plugins or /authors/Eric/ categories/Formatting/Bookmarklets

Hope That Helps,

-- BidiX
http://BidiX.info/

[1] http://tinyurl.com/5gx3bh (http://bidix.appspot.com/BidiX/namespaces/TiddlyHome/tiddlers/TiddlyHome%20Restful%20API.html)

[2] http://tinyurl.com/4regwn (http://bidix.appspot.com/BidiX/namespaces/TiddlyHome/tiddlers/A%20Model%20for%20a%20RESTful%20API.html)

 

From: "cd...@peermore.com"
Date: Tue, 17 Jun 2008 03:07:28 -0700 (PDT)
Subject: Re: Plugin Library: API concept

On Jun 17, 10:37 am, FND wrote:

> > You certainly need also to explain some relations between plugin-
> > repository-author like
> > /authors/Eric/categories/Formatting/plugins or /authors/Eric/
> > categories/Formatting/Bookmarklets

> I've been thinking about this as well - but I'm not sure whether
> combining selectors like that is semantically correct
> ("/foo/lorem/bar/ipsum" is essentially the same as
> "?foo=lorem&bar=ipsum", and is thus identical to "/bar/ipsum/foo/lorem").
> I might be missing the point here though (see above... ).

Technically speaking the path portion of a URL doesn't need to represent a hierarchical path. Practically speaking humans tend to want it to. Therefore what I tend to (try to) do in URL design is come up with a feasible set of hierarchies that allow a curious person to browse the resources that are available. So while /foo/lorem/bar/ipsum etc are all the same thing, they don't encourage the same use.

To do this it is important to think about what the primary resources or entities are in your system and be explicit about distinguishing those entities from information that could be considered attributes of those entities. One way to tell what is an attribute (in this context) is that attributes are usually harder to fit in a hierarchy.

Things that don't fit you may wish to put in a query string, as a sort of filter on the results at the current location.

In the plugin library situation you have a bit of a pickle, I think, because you really want to enable serendipitous browsing of the tiddlers such that people stumble onto the good stuff. You've got your primary entity of the plugin/tiddler but generally speaking people won't be looking via the primary entity. Instead they'll be looking by attributes and once they find things they like, before they do a download, the thing that matters is the container of the target: the thing which has information about the entity (where you can read and leave comments etc).

This suggests that while your _web service_ may have a primary entity of a tiddler, your _web application_, the library of plugins, may want for a different focus. If you want to encourage browsability, then you want several browsable entry points that eventually lead to the tiddler. Perhaps things like /authors/{author}/plugins and /categories/ {category}plugins and date related paths.

Here's a crazy idea: Have you considered using a blog engine, one that supports tags, as the presentation engine for the plugin store? Each plugin gets an automatically created blog entry, including a link to the canonical store (perhaps a bag in tiddlyweb?). You get tag and date browsing, comments and search for free.