Older blog entries for cdent (starting at number 126)

Bags can be created or updated over HTTP by using the HTTP API to access /bags/{bag_name} to send a PUT request containing a JSON bag. The content-type header must be set to application/json.

To make edits to a bag that already exists in the store the current user must pass the manage constraint on the bag. To create a new bag, the current user must pass the bag_create_policy.

See How can I use curl to create stuff in TiddlyWeb? for a simple example.

When a bag is GET or PUT as JSON the following form is used:

{
    "desc": "decription of the bag (may be be an empty string or absent)",
    "policy": {
        "read": [], 
        "write": [],
        "create": [],
        "delete": [],
        "manage": [],
        "owner": ""
    }
}

The policy may be an empty dict but the key must be present. The desc is optional.

Note that when doing a PUT what you send will fully replace anything that already exists.

See: How can I use curl to create stuff in TiddlyWeb?

Every tiddler has revisions. Every time a tiddler is changed, a new revision is created. Revisions are identified by an integer ID.

However, not all stores support revisions, so when a tiddler is changed, the existing single revision is replaced by the new one.

A list of revisions can be accessed at /bags/{bag_name}/tiddlers/{tiddler_title}/revisions and an individual revision at /bags/{bag_name}/tiddlers/{tiddler_title}/revisions/{revision}. Individual revisions are immutable.

In python code, retrieving a specific revision is done as follows:

    tiddler = Tiddler(title, bag_name)
    tiddler.revision = 4
    tiddler = store.get(tiddler)

If the revision does not exist a NoTiddlerError exception is raised. If revision is not set, the most recent revision is retrieved.

Wikipedia says that content negotiation

is a mechanism defined in the HTTP specification that makes it possible to serve different versions of a document (or more generally, a resource) at the same URI, so that user agents can specify which version fit their capabilities the best.

TiddlyWeb uses content negotiation to allow a user agent to declare which representation of a resource it prefers. Using the Accept header the user agent can declare that it wants a text/plain, text/html or application/json version of a resource (if available). With plugins other representations can be made available.

Content negotiation is a very significant contributor making any HTTP API powerful and flexible.

A user agent (often a person using a web browser) may also adjust the request URL to add an extension to simulate setting the Accept header. For example to get the plain text representation of a bag resource one might request:

GET /bags/mybag.txt

The default available extensions are:

• html to get text/html
• txt to get text/plain
• json to get application/json

TiddlyWebWiki adds:

• wiki to get text/x-tiddlywiki

Not all resources provide all representations. See the HTTP API for details.

Supported extensions can be extended by creating and configuring another serialization in a plugin.

Authorization is the management of access control: who or what gets access to particular resources or information. The authorization process requires that the requesting entity be authentic.

Except for two cases, authorization in TiddlyWeb is managed by policies.

The two exceptions are instances of the same problem: the creation of policies. This is controlled by configuration items: bag_create_policy and recipe_create_policy.

A config setting which declares who or what is able to create a recipe on the system. Since policies are associated with existing recipes, we need a separate mechanism for controlling creation. The recipe_create_policy does this. It's default value is an empty string, which means anyone can create a new recipe via a PUT to /recipes/{recipe_name}. Other options are:

ANY

Any authenticated user may create a recipe.

ADMIN

Any user with the ADMIN role may create a recipe.

Other options are possible by overriding existing code (tiddlyweb.model.policy:create_policy_check).

When a recipe is GET or PUT as JSON the following form is used:

{
    "recipe": [
        ["bag name 1", "select=tag:blog"],
        ["bag name 2", ""]
    ],
    "policy": {
        "read": [], 
        "write": [],
        "create": [],
        "delete": [],
        "manage": [],
        "owner": ''
    },
    "desc": "optional description of the bag (may be an empty string or absent)",
}

Note that when doing a PUT what you send will fully replace anything that already exists.

The filter documentation has been moved to its own specific space: tweb-filters.

These are things that can be done to make the documentation experience more palatable, but are not directly tied to the content itself.

• Improve HtmlCss
  • Formatting for tables.
  • Better line spacing throughout.
  • General or radical improvements as desired.
• More satisfactory search interface.
• Enable and encourage reply.

A constraint is one of several actions or permissions described in a policy. The constraint describes which user or role may perform the respective action:

Constraint	Bag	Recipe
read	view bag's tiddlers	view bag-filter pairs constituting the recipe
write	modify bag's tiddlers	unused
create	add tiddlers to bag	unused
delete	remove tiddlers from bag	unused
manage	delete bag, view and modify its policy	delete recipe, view and modify its policy
accept	skip validation for tiddlers	unused

cf. http://groups.google.com/group/tiddlyweb/msg/e0b3709851565dbe

An empty constraint list means there is no constraint; any user, including the anonymous user GUEST, can perform the action. NONE and ANY are special: NONE means the action may not be done, by anyone; ANY means any authenticated user (i.e. not GUEST) may perform the action.

If either of NONE or ANY are listed in a constraint, nothing else should be listed.