Additional documentation/discussion at GMOD_RPC_API/PHP
From: art@xxxx To: jogoodma@xxxxx Cc: art@xxxxxxx Subject: GMOD REST API feedback
Hi,
Firstly is there anyone there who I can skype for the first part of the meeting, to follow the discussion?
Secondly, I implemented most of the spec for the Oxford meeting. We have a bit of work to update to our latest libraries which I might do tonight. I have a few observations. I’ve already mentioned some of these to Giles so sorry if they’ve already been raised. I love the idea of the common API so in that spirit a few constructive criticisms:
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
I think the versioned API is a good idea, more important than strict REST compliance. I just wonder if the label *might* cause problems in a future publication or more importantly its takeup amongst purists. But REST is such a overused term that maybe this doesn’t matter.
difficulty is always getting NCBI ids for new projects in a timely matter, and for representing multiple samples of the same strain. It might be good to say that the ids should be NCBI taxonomy ids if possible, but that sequencing centres may also use ‘internal’ IDs. Effectively this means people should always fetch the …/organisms first to get the ids. This is really just requesting a textual relaxation in the spec. (I’ll also repeat my comment from the Oxford workshop that it seems slightly odd that the 2 GMOD URL-related specs use different methods of identifying organisms)
parameters. From the Sam Ruby O’Reilly REST book it certainly doesn’t seem to be taboo to use them. One point is that forcing everything into (possibly optional) positions in the URL makes both implementation, and requesting more difficult if you’re using a URI template-style implementation, as we are. If you allow query parameters the gene location could be:
http://yourmod.org/gmodrest/v<api version>/location/chromosome/<name>/gene[.xml | .json]?[min=[fmin/<int>]&[fmax/<int>]&[strand/(1 | -1)]
eg http://www.genedb.org/gmodrest/v1/location/chromosome/Tb927_v4.xml
and
http://www.genedb.org/gmodrest/v1/location/chromosome/Tb927_v4.xml&fmax=2000
This looks more natural to me, is more self-descriptive and is completely compatible with REST principles. The implementation point obviously isn’t that important as it’s a one-off cost but the I think the naturalness is. What do other people think?
indefinite. The example links either don’t work or return quite different XML. Is it in scope to produce a RNC or XML schema to tie this down?
Adrian