[MOBY-dev] MOBY 0.49 API online... nearly stable!

[Martin Senger]

Mark,
   Here is the first part of my comments to the API. I will put the next
parts (if any) directly into the biomoby.twiki.

   I strongly encourage other people to look at the API presented by Mark 
- he is right that *now* is the best time to influnce it. And also to have 
more ideas and points of view in the design phase is extremely useful.

   Cheers,
   Mrtin

-- 
Martin Senger

EMBL Outstation - Hinxton                Senger at EBI.ac.uk     
European Bioinformatics Institute        Phone: (+44) 1223 494636      
Wellcome Trust Genome Campus             (Switchboard:     494444)
Hinxton                                  Fax  : (+44) 1223 494468
Cambridge CB10 1SD
United Kingdom                           http://industry.ebi.ac.uk/~senger

-------------- next part --------------
"In BioMOBY, there are three catagories of input/output parameters..."

   Suggestion: call in consistentlly 'input/output data' (as also used
   in other places of the APi document(

"There are two forms of Primary parameter (...Simple...Collection)"

   It confuses me. Does it mean that a service can have more input
   parameters, each of them can be a collection? In that case why do
   you allow to have different types in one collection? Or does it
   mean that a service can have only (zero or) one primary parameter
   which can be a collection? In such case the variatey of element types
   is reasonable.

"There is currently only one form of Secondary input"

   Can a service have more that one secondary input? It should
   have. Why there is no collection of them? Generally speaking, I
   would not make difference between primary and secondary data (or
   parameters, whatever you decide to call them) in their structures. The
   difference should be in their usage (for example, the secondary data
   are not used for the service discovery). Why not to make it simpler
   and why not to have the same structure for both - with just a single
   attribute specifying this is primary and this is secondary?

Everything what was said about the input parameters/data above, should
be said and allowed also for outputs.

Attribute parameterName="..."

   If there is only one collection of simple parameters allowed, it
   does not need to be named (because its elements are). If there are
   more collections allowed, they should have elements of the same type
   and therefore they do not need to be named. This is, however,
   related to my comments above (sorry for repeating it here).

Query Ojbect - typo

"the authority (service provider URI)"

   I suggest to use consistently only one term (authority, service
   authority, provider, service provider,...).

"expandObjects: this flag will cause MOBY Central to traverse the
Class ontology to find services that operate not only on the Object
Class you are querying, but also any parent types or sub-objects of
that Object Class."

   Are you sure that this is correct? It seems to me that using this
   flag will return *all* services because all data types inherit from a
   base type 'Object'. So a service operating on 'Sequence objects'
   operates also on 'Object'. But perhaps it's enough to say where the
   traversal ends.

"The Query object structure is as follows:
   <inputObjects>
      <Input>
         <!-- one or more Simple or Complex Primary Parameters -->
   </Input>"

   Do I really need to include the whole Parameter definition? On
   another place the API says that I can query "by name from the Class
   ontology". It seems better to me.

   The same applies probably for the 'Service List Response
   Object'. Does this include name of data types or its whole
   structure?

"registerService...all elements except secondaryParameter are required"

   Why? I can imagine a service without any inputs (or using only
   default inputs). For example, "show me, what you have".

"findService
    * There are additional details..."

   Missing link with additional details.

"Output XML (by category):
     moby: 
         <Service>
              <![CDATA[WSDL document here]]..."

   A WSDL document is a valid XML piece - therefore is there any
   reason why to wrap it in a CDATA? We had this discussion already
   about embedding the XSD and it seemed to be resolved. You may
   remember that CDATA around the XML document may cause interoperability
   problems.

"ISA"

   Why not to have similar method for service hierarchy, not only for
   data type hierarchy?

"deregisterObject...
   <deregisterObject>
      <objectType>your_name at contact.address.com</objectType>
   </deregisterObject>"

   I do not see where I specify what object I am trying to deregister.

"If there is no inherent failure in your request, you will also
receive an email for confirmation. In that email, there will be an
http link that, when visited, will complete the deregistration
process."

   It should be done in a way that is able to automate (I would like
   to have programs to register and deregister). Which means the API
   must be either more precise by saying what "when visited" means, or
   (preferably) it should specify the format of the confirmation mail
   that has to be sent back.

"deregisterServiceType"

   How to deregister a name which occurs in two different branches of
   the service class ontology?