Re: [vwrap] Notes ... 9) query arguments to LLIDL

[Mark Lentczner <[e-mail]>]

Mark Lentczner wrote:
> **9) No one had concerns or issues with the addition of query arguments to LLIDL...


On Mar 24, 2010, at 11:28 AM, Dzonatas Sol wrote:
> Just to clarify from IETF session chat to make sure we are on the same page:
> 
> This is an acceptable standard query: /Resource/Path/<uuid>
> This is not standard, but an acceptable customization: /Resource/Path/<uuid>?encode=text&format=json

I don't have the context of the chat session, but, no, this doesn't speak to what I was getting at. Let me see if I can clarify:

The VWRAP foundation doesn't ever look at the form of URLs used to access resources. They are either "well known" (as in published), or received in response to a seed-capability request. In all cases, the entity using such a URL to access a resource never looks at the structure of the URL (except to perhaps verify that it doesn't resolve to localhost.) Any of these URLs would be acceptable:

	http://example.com/Resource/Path/f5771b22-239d-4497-9575-55494863c1ac
	http://example.com/f5771b22-239d-4497-9575-55494863c1ac?r=resource/path
	http://example.com/YWdlbnQ9OTkmb3A9cHJvZmlsZSZkZXRhaWw9Mw==
	http://path.resource.example.com/f5771b22-239d-4497-9575-55494863c1ac
	http://f5771b22-239d-4497-9575-55494863c1ac.example.com/resource-path

In other words, the provider of the resource is free to choose ANY scheme they like for associating URLs and resources. This is one of the essential tenets of the REST thesis.

> We shouldn't expect the customization to be supported across the board on all implementations. Instead, from feedback and various reads, we should make use of the Content-Type: field where possible instead of path arguments.
> 
> For example: Content-Type: text/json
> Or: Content-Type: application/xml+llsd

Correct. The second example URL you gave is clearly wrong in intent: The format negotiation is intended to be handled in the transport layer, not at the resource layer. When the transport is HTTP, HTTP has a well defined and widely implemented content negotiation system and that should be the sole method of content selection.

> Other operation arguments are probably best found in the body of the query rather than the header.
> Please clarify further is this what was not intended.

The LLIDL addition of support for query arguments enables a declaration of a resource that tells the client of that resource that some (or all) of the data supplied with the invocation should be added to the otherwise opaque URL for a resource. Without this addition, all client supplied data with a request would have to be in the request body.

Consider:
	%% thing/description
	<< { name: string, id: uuid, mod_time: date, thing/comments: uri }
	
	%% thing/comments
	?? { from: int, to: int }
	<< [ { n: int, when: date, who: uuid, text: string }, ... ]

The intent of this interface is that the client should take the URI returned for thing/comments in response to invoking a thing/description URL, and then append the desired range of comments to that URI.

So, for example, imagine the client has a URL for a given thing/description:
	http://example.com/gizmo-1231415144592/desc

It invokes that and gets back (in JSON):
	{
	  "name": "Widget",
	  "id": "f5771b22-239d-4497-9575-55494863c1ac",
	  "mod_time": "2001-04-01T23:03:00Z",
	  "thing/comments": "http://comments.example.com/gizmo-1231415144592"
	}

To get comments 1 through 25, it would then construct and invoke this URL:
	http://comments.example.com/gizmo-1231415144592?from=1&to=25

Nothing in VWRAP currently uses this style, and judging from past discussion there are many who would strongly discourage using it. Defining how to add the query args is tricky, full of corner cases, and would be a fair bit of work, especially if the base URI already has query args!

That said, backends seem to often use this style of URL, in part because it enables caching based on some of the client's arguments. Because there was desire to use a single IDL language for specifying REST like interfaces, we implemented the '??' feature of LLIDL here at Linden Lab. It was my point that I think VWRAP implementors will find this feature generally useful, even if not used directly by the standards, for the same reasons as we did.

Lastly, I was asking if implementors felt a similar need for being able to define client supplied arguments that go into the path of a URL. Inside of Linden Lab there is some desire for this, though less so than the query argument declaration. Further, it is also less clear just how much expressive power is needed for path arguments.

	- Mark

Mark Lentczner
Sr. Systems Architect
Technology Integration
Linden Lab

[e-mail]

Zero Linden
[e-mail]