TiddlyHome RSS feed

Experimental iTW available at TiddlyHome 2.0

2008-07-07 05:58

Just as a proof of concept, an iTW is available at http://tiddlyhome.appspot.com/BidiX/tiddlywikis/iTW . The full TiddlyWiki is available (in Safari) at http://tiddlyhome.appspot.com/BidiX/tiddlywikis/iTW.html.

Data Model

2008-06-24 09:22

User is an extension of Google User with a username
User owns Namespaces
User owns Tiddlywikis
Namespace owns Tiddlers
TiddlyWiki, in a Namespace, references Tiddlers

Some rules :

only the owner of an entity (TiddlyWiki, Namespace, Tiddler) can edit it
a Namespace (or a TiddlyWiki) can be private.
only the owner of a private Namespace (or a Tiddlywiki) can see it

TiddlyHome Restful API

2008-06-17 05:59

Following this model above the TiddlyHome API.

URI Resources

User

/<username>
The resource <user_id> doesn't have is container specified. Need more developments.

Namespace

/<username>/namespaces
Namespace container owns by <username>.
/<username>/namespaces/<namespace_id>
<namespace_id> owns by <username>.

Tiddler

/<username>/namespaces/<namespace_id>/tiddlers
Tiddler container in <namespace_id> owns by <username>.
/<username>/namespaces/<namespace_id>/tiddlers/<tiddler_id>
<tiddler_id> in <namespace_id> owns by <username>.

Tiddlywiki

/<username>/tiddlywikis
Tiddlywiki container own by <username>.
/<username>/tiddlywikis/<tiddlywiki_id>
<tiddlywiki_id> owns by <username>.

Requests to TiddlyHome Service

Actually PUT is not implemented.

For now requested content-type (HTTP Request header) are not interpreted. All responses, except when specified, are in Content-type: text/html.

Return code conform to model.

User

GET /<username>
Return username and mail address.Need more developments.
GET www.google.com/accounts/ServiceLogin?...
For now available only from a browser. Redirect to the current page once the login (or logout) is done.

Namespace

GET /<username>/namespaces
List of Namespace own by <username>.
POST /<username>/namespaces
Create or update namespace with these attributes :
- name
- access: 'on' | ''
- owner_name:
- previous_name: if different from name, previous name is deleted.
- return_url: response redirect to this url
GET /<username>/namespaces?new
Return a form that submit a POST /<username>/namespaces. This form is empty.
GET /<username>/namespaces/<namespace_id>
return an HTML page for <namespace_id> details.
GET /<username>/namespaces/<namespace_id>?edit
Return a form that submit a POST /<username>/namespaces. This form is filled with <namespace_id> details.
DELETE /<username>/namespaces/<namespace_id>
GET /<username>/namespaces/<namespace_id>?delete
Delete <namespace_id>.

Tiddlywiki

GET /<username>/tiddlywikis
List of Tiddlywiki own by <username>.
POST /<username>/tiddlywikis
Create or update tiddlywiki with these attributes :
- name
- namespace_name
- access: 'on' | ''
- title
- subtitle
- <tiddler_title>: 'on' | '' (for each tiddler in <namespace_name>)
- previous_name: if different from name, previous name is deleted.
- return_url: response redirect to this url
PUT /<username>/tiddlywikis/<tiddlywiki_id>?put
POST /<username>/tiddlywikis/<tiddlywiki_id>?put
Not documented
GET /<username>/tiddlywikis?new
Return a form that submit a POST /<username>/tiddlywikis. This form is empty.
GET /<username>/tiddlywikis/<tiddlywiki_id>
return an HTML page for <tiddlywiki_id> details.
GET /<username>/tiddlywikis/<tiddlywiki_id>.html
return a TiddlyWiki page for <tiddlywiki_id>.
GET /<username>/tiddlywikis/<tiddlywiki_id>.xml
return a xml page in RSS format for <tiddlywiki_id>.
GET /<username>/tiddlywikis/<tiddlywiki_id>?edit
Return a form that submit a POST /<username>/tiddlywikis. This form is filled with <tiddlywiki_id> details.
GET /<username>/tiddlywikis/<tiddlywiki_id>?upload
Return a form that upload a TiddlyWiki a POST /<username>/tiddlywikis/<tiddlywiki_id>?put.
DELETE /<username>/tiddlywikis/<tiddlywiki_id>
GET /<username>/tiddlywikis/<tiddlywiki_id>?delete
Delete <tiddlywiki_id>.

Tiddler

GET /<username>/namespaces/<namespace_id>/tiddlers
List of Tiddler in <namespace_id>.
POST /<username>/namespaces/<namespace_id>/tiddlers
Create or update a tiddler with these attributes :
- title
- tags
- text
- html: wikified text
- previous_title: if different from title, previous title is deleted.
- return_url: response redirect to this url
GET /<username>/namespaces/<namespace_id>/tiddlers?new
Return a form that submit a POST /<username>/namespaces/<namespace_id>/tiddlers. This form is empty.
GET /<username>/namespaces/<namespace_id>/tiddlers/<tiddler_id>.html
return an HTML page <tiddler_id> only with html content for publishing (Tiddlyhomes use this for HomePage and HelpPage).
GET /<username>/namespaces/<namespace_id>/tiddlers/<tiddler_id>.txt
return a text/plain page for <tiddler_id> text.
GET /<username>/namespaces/<namespace_id>/tiddlers/<tiddler_id>.js
return a text/plain page for <tiddler_id> text.
GET /<username>/namespaces/<namespace_id>/tiddlers/<tiddler_id>.tw
return a text/plain page for <tiddler_id> in TiddlyWiki StoreArea format.
GET /<username>/namespaces/<namespace_id>/tiddlers/<tiddler_id>?edit
Return a form that submit a POST /<username>/namespaces/<namespace_id>/tiddlers. This form is filled with <tiddler_id> details.
DELETE /<username>/namespaces/<namespace_id>/tiddlers/<tiddler_id>
GET /<username>/namespaces/<namespace_id>/tiddlers/<tiddler_id>?delete
Delete <tiddler_id>.

A Model for a RESTful API

2008-06-17 05:58

This article suggests a model for a RESTful API usable in a browser without using AJAX and that manage a suffix to request a particular content-type.

This model is implemented has a generic extension to Google Engine webapp. See it in action in TiddlyWiki context at TiddlyHome

Resource

The typical URI of a resource is :

/<type>s/<id>[.<format>]

like in /tiddlywikis/HowTo.html.

To obtain the list of all resources of a type simply :

/<type>s

Membership relation

When the resource is linked to an other resource, especially to explain membership, the URI becomes :

/<parent_type>s/<parent_id>/<children_type>s/<children_id>

(ex: /tiddlywikis/HowTo/tiddlers/Upload ).

Basic functions on resource

In RESTful API, the CRUD basic functions on a persistent resource can be accessed using HTTP methods :

HTTP Method	Function
`GET <uri_id>`	Read <resource_id>
`PUT <uri_id>`	Create or Update <resource_id>
`DELETE <uri_id>`	Delete <resource_id>
`POST <a_form>`	Ask service to Create, Update or Delete some resource using <a_form>

API to manage a resource

API call	Application function called
`GET /<type>s`	Type.list()
`GET /<type>/<id>[.<format>]`	id.display[_in_<format>]()
`GET /<type>/<id>[.<format>]`	404
`PUT /<type>s/<id>`	id.put()
`DELETE /<type>s/<id>`	id.delete()
`POST /<type>s`	Type.create_or_update()

RESTful extensions for browser

Since methods PUT and DELETE can't easily be activated in a browser (except using AJAX). The query_string part of the URL is used to simulate PUT or DELETE.
On server, the Handler first changes the query_string in the corresponding method :

URL with query_string	API Call
`GET /<type>s/<id>?delete`	`DELETE /<type>s/<id>`
`GET /<type>s/<id>?put`	`PUT /<type>s/<id>`
`GET /<type>s?new`	`GET /<type>s` - with an attribut in_form = True
`GET /<type>s/<id>?edit`	`GET /<type>s/<id>` - with an attribut in_form = True

Specifying Content-type

To easily specify the content-type required, a suffix is added to the resource like : .html, .xml, .txt .js ...

Return codes

Finally HTTP Status are used in response to HTTP request. Their normalised meaning are used, sometimes with some restrictive sense in the API context.

HTTP Code	HTTP status message	API Meaning
200	OK	Ok
201	Created	New entity created
400	Bad Request	The URL can't be processed (Type doesn't exist, bad format requested ...)
401	Unauthorized	The logged user is not authorized to execute this action
403	Forbidden	Action is not allowed
404	Not Found	Resource doesn't exist
405	Method not allowed	This resource doesn't allow this method (operation)
406	Not acceptable