Re: [Treebase-devel] [PhyloWS] PhyloWS, CQL, NeXML on TreeBASE2

[Hilmar L. <hl...@ne...>]

On Jul 3, 2009, at 6:13 PM, William Piel wrote:

> cool stuff.

I agree - the API is definitely heading in the right direction.

I suggest some tweaks:

>
> I notice that this departs a bit from the phylows that is proposed  
> here.  For example, the proposed phylows puts "/find/" before "/ 
> tree/", whereas you have it the other way.

Right, this is not in compliance with the spec. find/ comes first as  
it changes the resource from a record and its URI to a finder.

I.e., although it's possible that we change the spec, I don't see the  
reason that would justify that.

In general, note that REST APIs at present aren't formally declared in  
a descriptor document that a general purpose validator could use and  
validate compliance. So really extra care needs to be taken to comply  
with the spec, or otherwise it's not a spec but a loose prescription.  
It seems like we should also implement a PhyloWS validator that  
uncovers violations quickly.

> And the other major difference is that the proposed phylows suggest  
> that to search on trees you do something like:
>
> /phylows/find/tree/?name=Primates
>
> whereas you are implementing:
>
> /phylows/taxon/find/?name=Primates&recordSchema=tree

Note BTW that a taxon finder is a custom addition to the API. Which is  
fine in principle, except that I'd suggest you conform to the pattern  
in the API spec and put find/ first.

Also, find/taxon/ would imply that you are finding (and returning)  
taxa, which if I understand correctly is not the case - rather it  
seems you have one query parameter in the URI path (namely that you  
are searching by taxon?) and one in the query string. So if this is  
searching trees, it needs to be find/tree/, and if you are matching  
against taxon names, the query parameter needs to be tb.taxon.name or  
whatever the blessed metadata term for this purpose is.

Third, recordSchema=tree means that you want records back in the tree  
schema. Unless you have invented that schema meanwhile, this is in all  
likelihood not what you want. Rather, the value should be nexml I  
suppose. find/tree already implies that you are finding (and  
returning) trees, so there is no point in expressing that redundantly  
in the query string. You might want to specify that you only want the  
tree and not also the matrix, but that would be a separate query  
parameter and should not be confounded with the return format.

	-hilmar


-- 
===========================================================
: Hilmar Lapp  -:- Durham, NC -:- informatics.nescent.org :
===========================================================