[Registry-dev] Extensible search API - coming back

[Sanjiva Weerawarana]

Hi Glen,

> OK, let's try this again, once more with feeling! :)
> 
> * We should NOT NOT NOT have an isDirectory() flag on Resource.  Ew!
> 
> * We SHOULD have a Directory (or whatever) class which extends or
>   implements Resource, and also adds methods for walking the children.
> 
> * A query result should be a ResourceCollection (or whatever we call
>   it)
> 
> * IMO we should support each entry in a ResourceCollection having
>   both a path (to the associated Resource) and an arbitrary set of
>   properties in order to carry metadata.  I believe this is
>   compatible with APP's notion (and serialization) of a collection?
> 
> We got this mostly right with the first prototype we built while dims 
> and I were in Colombo... please let's fix this ASAP.

I'm fine with this .. there was some argument about why this makes sense; 
now I forget the details - I'll let Chathura reply :).

BTW, at a REST level- I do have to agree that a directory is simply a 
resource with a different representation. In fact, we can drop 
"isDirectory" and simply have a standard media type we return.

In effect that's what Apache HTTPD does when you ask it to auto generate 
the list of files for a dir when there's no index.html.

So for example, if we return an Atom feed for a directory, we could have 
some extra parameter for the content type to indicate this is directory 
and not just any old feed.

OK so I lied; I am (at least partly) arguing for the current design ;-).

I remember being torn by Chathura's argument - so we'll let him tear you 
apart inside too ;-).

>>> In all above types, we can put the main data part (e.g. comment text, 
>>> tag string, rating value) as the resource content and
>>> put all other data as resource properties (e.g. number of taggings).
> 
> See above - I think with a collection it's fine to include metadata in 
> the result data.

For a collection its fine, but I don't understand what resource properties 
is for a resource and how you get at that. GET /a/b/r1 must simply return 
whatever representation the system can based on the content negotiation 
headers the client has put (Accept: whatever).

>> - resource: /a/b/r1
>>     Return the natural representation of the resource with the content 
>> type properly set
>> - comments: /a/b/r1?comments
>>     Return an atom feed containing all comments against a/b/r1
>> - tags: /a/b/r1?tags
> 
> Mostly +1, but I'm still not totally convinced on using the query string 
> for this.  Note that other chars like comma, slash and semicolon are 
> also available to us, so "r1;comments" or "r1/comments" could be used 
> here too.  Both of these have the nice quality that you can easily 
> continue the hierarchy downward "r1;comments/2;tags"....

Let's please not go overboard. I like the simplicity of the query string 
and we can always change if we need to - after all these are "just links".

Tagging comments? IMO that's quite overboard.

I'm +1 to having ?comments and ?comment=n both, similar to ratings and rating.

>> I am not sure I see how users fit in .. other than as above. That is, 
>> I'm not sure something like /user/xyz is a useful resource to have. 
>> That can be achieved by doing a query saying "show me everything that 
>> user x authored" for example.
> 
> I really like /users/xyz as an explicit resource.  That lets you do cool 
> stuff in the future (even if we don't yet) like profiles, RDF 
> references, etc... and I definitely like that you don't need a specific 
> query language in order to know that /users/xyz will link you to 
> everything that user has authored - just like tags/tag.

True. So you see it returning a simple feed basically?

Maybe we need to think thru /tag/{tag} and /user/{user} carefully. 
Basically they are special URIs that map to some custom query. So maybe we 
should make that pluggable .. allow the user to map a URI to a query .. 
essentially virtual directories again. All we need to do is for any 
unknown URIs just look it up in that table and see whether there's a query 
matching and if so execute it and send the resource collection back. That 
way we don't need to "hard code" any special URIs like /tag or 
/user/{user}. (Notice that I prefer /tag and /user instead of /tags and 
/users .. that seems to be the convention in other places.)

So we need some API like
	addVirtualPath ("/user/{user}", queryPath)
Note that the first argument must be a URI template .. and each of the 
identified parts will become a variable that is passed to the query in the 
order they appear in. This is standard WSDL 2.0 / URI template stuff so no 
problem.

Or, take it one step further ..
	alias ("/user/{user}", resourcePath)
Just introduce an alias .. and if the 2nd argument points to a resource 
which happens to be to a query (remember we know that from the media type 
of the resource), we actually execute that before sending the response. 
Otherwise this acts like a regular alias to map one resource to another 
resource.

TooCleverByHalf again?

Sanjiva.
-- 
Sanjiva Weerawarana, Ph.D.
Founder, Chairman & CEO; WSO2, Inc.; http://www.wso2.com/
email: sanjiva at wso2.com; cell: +94 77 787 6880; fax: +1 509 691 2000

"Oxygenating the Web Service Platform."