BioMOBY

What follows is the XML payload for the various MOBY Central procedure calls. While this will be a definitive, programming language-independent description of the XML that should be exchanged among MOBY-compatible software, it is not a good place to start if you're new to MOBY.

You should read further only if you plan to implement this API in a programming language. Where input/output/secondary parameter types are required, they are referred to in a comment section rather than explicitly writing them into the XML.

In all cases where you are required to enter a term from the Object, Namespace, and Service type ontologies you may use enter the human readable name (e.g. "Blast", or "GO_Term") or you may use the LSID referring to that term. If you are using ontologies other than the BioMOBY ontologies, then you must use an LSID. MOBY Central will sanity-check and traverse only the BioMOBY ontologies.

Function	Returns
findService	Locate a service instance
retrieveService	Definition for a service instance.
retrieveResourceURLs	URLs of all registered services.
retrieveServiceProviders	Names of all registered service providers.
retrieveServiceNames	Names of all registered services.
retrieveServiceTypes	Definitions and registration details of all registered service types.
retrieveObjectNames	Definitions and registration details of all registered object types.
retrieveObjectDefinition	Class definition, full registration details for that class type.
retrieveNamespaces	List of all registered namespaces
retrieveObjectSchema	XML schema representation of a particular object class.
Relationships	List of MOBY object classes having a specified relationship with the given class

The following procedure calls must be implemented by a MOBY Central registry that also allows write access:

Function	Returns
registerObjectClass	Register a new object class.
deregisterObjectClass	Deregister a deprecated object class.
registerServiceType	Register a new service type.
deregisterServiceType	Deregister a deprecated service type.
registerNamespace	Register a new namespace.
deregisterNamespace	Deregister a deprecated namespace term
registerService	Register a new service instance.
deregisterService	Deregister a service instance.

The following procedure calls may be implemented in a MOBY Central registry:

Function	Returns
DUMPneeds a link	dump out the entire database
registerServiceWSDL	register a service based on an input WSDL document

registerService

Input XML

      <registerService>
         <Category>some_category_here</Category> 
         <serviceName>YourServiceNameHere</serviceName>
         <serviceType>TypeOntologyTerm</serviceType>
         <authURI>your.URI.here</authURI>
         <signatureURL> http://some.URL.org/path/to/RDF/file </signatureURL>
         <URL>http://URL.to.your/Service.script</URL>;
         <contactEmail>your_name@contact.address.com</contactEmail>
         <authoritativeService>1 | 0 </authoritativeService>
         <Description><![CDATA[
               human readable COMPREHENSIVE description of your service]]>
         </Description>
         <Input>
              <!-- zero or more Primary -->
	      <!-- (Simple and/or Collection) Articles -->
              <!-- each of these Articles will appear -->
	      <!-- EXACTLY ONCE in the input to the service -->
         </Input>
         <secondaryArticles>
              <!-- zero or more INPUT Secondary (Parameter) Articles -->
              <!-- each of these Articles will appear -->
	      <!-- EXACTLY ONCE in the output from the service -->
         </secondaryArticles>
         <Output>
              <!-- zero or more Primary -->
	      <!-- (Simple and/or Collection) Articles --> 
         </Output>
      </registerService>

Output XML

Registration Object

Notes

• There are three ways to call this method:
1. With all arguments except signatureURL filled - intended for services in 'testing phase' only
• This will register the service as described by the other arguments and you will be able to call the deregisterService method to remove this service
• NOTE: there is no security in registering a service in this way. The deregisterService method is open to all clients, and your service may be removed from the registry at any time either accidentally or mischeviously.
• NOTE: by convention, a particular Client application MAY use the absense of a signatureURL as a filter to highlight or remove unstable/development-stage services from its list of discovered services. As such, your service may not appear to be discovered by some client programs
2. With all arguments filled - intended for 'production' quality services
• This will register the service as described by the arguments
• These services CANNOT be deregistered by the deregisterService method, and must instead use a call to the RDF agent as described below
• The RDF document returned in the Registration Object from MOBY Central in response to this call (the "Signature RDF") is expected to be placed at the URL specified in the signatureURL parameter. Editing/removing this Signature RDF is the means by which this services will be updated or deregistered in the future.
3. With only a signatureURL - initiates a call to the RDF Agent
• This will call an 'Agent' to GET the URL provided. At that URL there should be a properly formatted Signature RDF describing the services hosted at that site. This can be created manually, or can be copied from the Registration object's RDF block in response to a registerService call. The document at a signatureURL MAY contain more than one Signature RDF entry, with each mygrid:serviceDescription block concatenated within a single RDF file.
• If that RDF document contains a new Signature RDF, that new service (if valid) will be registered
• An new service is recognized by the presence of a novel authorityURI + serviceName (predicates dc:publisher and mygrid:hasServiceNameText) in a mygrid:serviceDescription block of the Signature RDF document
• If the retrieved RDF document contains a modified Signature RDF, the currently-registered service will be updated in MOBY Central
• An updated service is recognized by the presence of a known authorityURI + serviceName in a Signature RDF service description, where other parameters have been altered compared to what is in the MOBY Central registry
• uncertain: the Agent will refuse to modify the service if you do not also modify your service's LSID.
• If a Signature RDF is missing from the document, the service formerly described by that RDF will be deregistered from MOBY Central
• 'Missing' is determined by a query to MOBY Central for the set of Services that should be present at a particular SignatureURL.
• This is the only method of removing a service from the registry if it has been registered with a SignatureURL.
• A service must have at least one Input OR Output Object Class.
• serviceName must comply with rules for method names of a web service. i.e. must be include only characters [A-Za-z0-9_] and begin with a letter.
• The object classes, namespaces, and service types must all exist for the registration to be successful, so make sure you register these first, or ensure that they already exist in their respective ontologies.
• The authoritativeService tag is used to indicate whether or not the registered service is "authoritative" for that transformation. i.e. if you are "authoritative" anyone else performing the same transformation would have to have obtained the information/code to do so from you. This is similar to, but not necessarily identical to, mirroring someone elses data, since the data in question may not exist prior to service invocation.
• Only input secondary articles are defined during registration; output secondary objects are entirely optional and may or may not be interpreted client-side using their articleName tags.
• When registering a service, the registration object that you are returned contains an extra XML element with the RDF tag. Inside of this element is the RDF document corresponding to your service signature. MOBY Central will expect to be able to recover that RDF document when it calls a GET on the URL that you provide in the signatureURL element of the registerService method. Depending on the configuration of the MOBY Central registry you are using, an agent may call this document on a regular basis, and update your registered service with whatever it finds there. If you wish to de-register your service, just remove that document (or the portion of that document corresponding to your service).
• The names of each article may not contain spaces or other special characters, like:
  

  ~`!@#$%^&*()=+{[]}:;'",.<>?/|\

• What category should I use? Currently, there are five supported categories of moby service: 'moby', 'moby-async', 'doc-literal', 'doc-literal-async' and 'cgi'.
  • 'moby' is RPC encoded synchronous
  • 'moby-async' is RPC encoded asynchronous
  • 'doc-literal' is document-literal encoded synchronous
  • 'doc-literal-async' is document-literal encoded asynchonous
  • 'cgi' is HTTP POST synchronous

findService

Input XML

(Service Query Object)

        <findService>
              <!--  Service Query Object -->
        </findService>

Output XML

Service List Object

Notes

• This single call replaces all of the "locateServiceBy*" calls in the prototype API
• There are additional details that affect the behaviour of MOBY Central when making this call.

retrieveService

Input XML

        <retrieveService>
            <Service authURI="your.URI.here" serviceName="MyService"/>          
        </retrieveService>

Output XML

Three protocols are (in principle) available:

• moby

           <Service authURI="your.URI.here" serviceName="MyService" 
  	 lsid='urn:lsid:authority.uri:serviceinstance:id'>
                <![CDATA[WSDL document here]]>
           </Service>
  

Notes

• authURI and serviceName attributes are sufficient to identify a unique service, and both are required in the element.
• The WSDL that is returned is not currently valid. It will only become valid once we have the ability to convert our class ontology into an XML schema. In addition, the WSDL that is returned does not necessarily describe the actual interface of the service. In the BioMOBY system, you are allowed to pass more complex objects to a service, and the service is allowed to pass more complex objects back to you, so long as they obey the parentage rules of the class ontology. As such, the WSDL that you receive is the minimal interface for the service, not necessarily the actual interface.
  The use of WSDL in the BioMOBY system is subject to change in future revisions, and is provided at this time only to facilitate the creation of service stubs on the client side using the commonly available WSDL parsers.

retrieveServiceProviders

Input XML No input required.

Output XML

        <serviceProviders>
           <serviceProvider name="your.URI.here"/>
                ...
        </serviceProviders>

Notes

retrieveResourceURLs

Output XML

  <resourceURLs>
       <Resource name="Service" url="http://mobycentral.org/RESOURCES/MOBY-S/Services/>
       <Resource name="Object" url="..."/>
       <Resource name="ServiceInstance" url="...X..."/>
       <Resource name="Full" url="...Y..."/>
   </resourceURLs>

Notes

• Finds the URL from which the RDF of a MOBY Ontology can be retrieved by HTTP GET. There are five possible ontology names: "Service", "Object", "Namespace", "ServiceInstance", or "Full" (Full retrieves all of the ontologies)

retrieveServiceNames

Input XML No input required.

Output XML

        <serviceNames>
           <serviceName name="serviceName" authURI="your.URI.here" 
	   lsid='urn:lsid:authority.uri:namespace:id'/>
                ...
        </serviceNames>

Notes

• Retrieves minimal information about all registered MOBY services
• Name
• Authority
• LSID

retrieveServiceTypes

Input XML No input required.

Output XML

        <serviceTypes>
           <serviceType name="serviceName" lsid='urn:lsid:authority.uri:servicetype:id'>
                  <Description><![CDATA[free text description here]]></Description>
                  <contactEmail>email@address here</contactEmail>
                  <authURI>your.URI.here</authURI>
           </serviceType>
                ...
        </serviceTypes>

Notes

• Gets a full dump of the Service Type ontology as MOBY XML (excluding relationships)
• To retrieve the service type ontology as RDF, use retrieveResourceURLs and perform an HTTP GET on the contents of the element with tagname Service.

retrieveObjectNames

Input XMLNo input required.

Output XML

        <objectNames>
           <Object name="objectName" lsid='urn:lsid:authority.uri:namespace:id'>
                  <Description><![CDATA[free text description here]]></Description>
           </Object>
                ...
        </objectNames>

Notes

• Gets a dump of all Object Class names from the Class ontology, excluding relationships
• To retrieve the Object class ontology as RDF, use retrieveResourceURLs and perform an HTTP GET on the contents of the element with tagname Object.

retrieveObjectDefinition

Input XML

      <retrieveObjectDefinition>
           <objectType>ExistingObjectClassname</objectType>
      </retrieveObjectDefinition>

Ouptut XML

        <retrieveObjectDefinition>
            <objectType lsid='urn:lsid:authority.uri:namespace:id'>ObjectClassName</objectType>
            <Description><![CDATA[
                    human readable description
                    of data type]]>
            </Description>
            <Relationship relationshipType="RelationshipOntologyTerm" 
	    lsid='urn:lsid:authority.uri:namespace:id'>
               <objectType articleName="SomeName" lsid='urn:lsid:authority.uri:namespace:id'>ExistingObjectType</objectType>
            </Relationship>
            ...
            <authURI>your.URI.here</authURI>
            <contactEmail>owner@their.address.com</contactEmail>
        </retrieveObjectDefinition>

Notes

• Retrieves the full declaration of a class, as defined by the XML used to register it.

retrieveNamespaces

Input XML No input required.

Output XML

        <Namespaces>
           <Namespace name="namespace" lsid='urn:lsid:authority.uri:namespace:id'>
                  <Description><![CDATA[free text description here]]></Description>
                  <contactEmail>email@address here</contactEmail>
                  <authURI>your.URI.here</authURI>
           </Namespace>
                ...
        </Namespaces>

Notes

Gets a dump of all registered namespaces.

To retrieve the namsepace type ontology as RDF, use retrieveResourceURLs and perform an HTTP GET on the contents of the element with tagname Namespace.

retrieveObjectSchema

Input XML

        <retrieveObjectSchema>
           <objectType>ObjectType | all</objectType>
        </retrieveObjectSchema>

Output XML

        <Objects>
           <Object name="ObjectOntologyTerm" lsid='urn:lsid:authority.uri:namespace:id'>
                  <Schema><![CDATA[
                      <XSD schema here>]]>
                  </Schema>
           </Object>
                ...
        </Objects>

Notes

• Retrieves an Object definition as W3C XML Schema (XSD)
• This may take a considerable amount of time before it is coded, as it is a non-trivial problem
• not yet implemented

Relationships

Input XML

        <Relationships>
          [ <objectType>OntologyTerm</objectType> | 
	  <serviceType>OntologyTerm</serviceType> ] 
         <relationshipType>RelationshipOntologyTerm1</relationshipType>
         <relationshipType>RelationshipOntologyTerm2</relationshipType>
                 ...
         <direction>root|leaves</direction>
         <expandRelationship>1|0</expandRelationship>
        <Relationships>

Output XML

        <Relationships>
           <Relationship relationshipType="RelationshipOntologyTerm1" 
	   lsid='urn:lsid:authority.uri:namespace:id'>
                [ <objecctType lsid='...' articleName='foo'>OntologyTerm</objectType> | 
		<serviceType lsid='...'>OntologyTerm</serviceType> ]
                       ...
           </Relationship>
           ...
        </Relationships>

Notes

• Retrieves the Entity (Object or Service) Classnames that stand in 'X' relationship to the given entity type based on the regarding Class ontology, where X is the relationship(s) specified in the input message
• The result list is composed of all entities which are related to the query entity by any relevant relationship instance. The given direction dictates which relationship instances are considered:
  • ISA: suppose a relationship instance R:= A ISA B. If direction is 'root' R is considered if B is the query entity. If direction is 'leaves' R is considered if A is the query entity.
  • HAS: suppose a relationship instance R:= A HAS B. If direction is 'root' R is considered if A is the query entity. If direction is 'leaves' R is considered if B is the query entity.
  • HASA: suppose a relationship instance R:= A HASA B. If direction is 'root' R is considered if A is the query entity. If direction is 'leaves' R is considered if B is the query entity.
• If the expandRelationships flag is NOT set, the response will contain only the classnames that lie immediately in that relationship to the given entity.
• If the expandRelationships flag is set, the ontology will be traversed in the following way:
  • ISA: the ontology will be traversed along the ISA path in the given direction; up to the root entity ("Object" or "Service") for 'root' direction, down to the ontology leaves for 'leaves' direction
  • HAS(not applicable to Service ontology): Object ontology will be traversed along the ISA path as described above. For each node in the resulting ISA hierarchy all objects related by HAS will be added to the output as a flattened list (direction dependent rules for considering relationships apply). The HAS, HASA, or ISA realtionships of these will NOT be followed.
  • HASA(not applicable to Service ontology): Object ontology will be traversed along the ISA path as described above. For each node in the resulting ISA hierarchy all objects related by HAS will be added to the output as a flattened list (direction dependent rules for considering relationships apply). The HAS, HASA, or ISA realtionships of these will NOT be followed.

registerObjectClass

Input XML

        <registerObjectClass>
            <objectType>NewObjectType</objectType>
            <Description><![CDATA[
                    human readable description
                    of data type]]>
            </Description>
            <Relationship relationshipType="RelationshipOntologyTerm">
               <objectType articleName="SomeName">ExistingObjectType</objectType>
               ...
            </Relationship>
            ...
            <authURI>your.URI.here</authURI>
            <contactEmail>You@your.address.com</contactEmail>
        </registerObjectClass>

Output XML

Registration Object

Notes

• Registers a new object Class into the Class ontology
• Class names are unique within the ontology, and there is only one canonical MOBY Class ontology.
• You can envision this as simply registering a new node into the class ontology graph, and creating the primary connections from that node.
• MOBY, by default, supports three types of class relationships: ISA, HAS, and HASA (these are the relationship ontology terms)
  • foo ISA bar is a straight inheritence, where all attributes of bar are guaranteed to be present in foo.
  • foo HAS bar is a container type, where bar is an object inside of foo in one or more copies.
  • foo HASA bar is a container type, where bar is an object inside of foo in one copy only
• Notice that, in a HAS and HASA relationships, it is necessary to indicate an article name for each contained object type. Thus, for example, you could have a sequence object that contained a String object with name "nucleotideSequence" and an Integer object with the name "sequenceLength".
  
  Note: These article names must be unique among all relationships, including those contained by the parent node.
• Article names for each contained object type may not contain spaces or other special characters, like:
  

  ~`!@#$%^&*()=+{[]}:;'",.<>?/|\

deregisterObjectClass

Input XML

        <deregisterObjectClass>
          <objectType>ObjectOntologyTerm</objectType>
        </deregisterObjectClass>

Ouptut XML

Registration Object

Notes

• Removes an Object Class from the Class ontology
• You should only deregister classes that you yourself registered!
• You may not deregister object classes that are being used as input or output by any service
• You may not deregister object classes that are in a ISA or HASA relationship to any other object class.

registerServiceType

Input XML

        <registerServiceType>
         <serviceType>NewServiceType</serviceType>
         <contactEmail>your_name@contact.address.com</contactEmail>
         <authURI>your.URI.here</authURI>
         <Description>
           <![CDATA[ human description of service type here]]>
         </Description>
         <Relationship relationshipType="RelationshipOntologyTerm">
           <serviceType>ExistingServiceType</serviceType>
           <serviceType>ExistingServiceType</serviceType>
         </Relationship>
        </registerServiceType>

Output XML

Registration Object

Notes

• Registers a new node in the service ontology
• serviceTypes are unique within the service ontology, and there is only one canonical MOBY service ontology.
• The only relationship ontology type currently supported by MOBY is the "ISA" relationship.
• Services described to be in ISA relationship with the new service type must exist or this registration will fail.
• All parameters are required.
• Email must be a valid email address.

deregisterServiceType

Input XML

        <deregisterServiceType>
          <serviceType>ServiceOntologyTerm</serviceType>
        </deregisterServiceType>

Ouptut XML

Registration Object

Notes

• Deregisters a service term from the service ontology
• Will fail if any current services are instances of that service type
• Will fail if any other service types inherit from that service type.

registerNamespace

Input XML

        <registerNamespace>
           <namespaceType>NewNamespaceHere</namespaceType>
           <contactEmail>your_name@contact.address.com</contactEmail>
           <authURI>your.URI.here</authURI>
           <Description>
              <![CDATA[human readable description]]>
           </Description>
        </registerNamespace>

Output XML

Registration Object

Notes

• Registers a new namespace in the namespace controlled vocabulary (CV)
• Namespaces are unique within the namespace CV and there is only one canonical MOBY namespace CV.
• Must provide a valid email address
• All parameters are required.

deregisterNamespace

Input XML

 
        <deregisterNamespace>
           <namespaceType>MyNamespace</namespaceType>
        </deregisterNamespace>

Outut XML

Registration Object

Notes

• Removes a namespace from the controlled vocabulary
• Will fail if that namespace is being used by any services

deregisterService

It is intended that this method will ultimately be deprecated. A requirement for this to happen is the completed transition from a function-call based registration process to an RDF-document-based registration. For the time being, it remains in use.

Under the current function-call based procedure, a service is registered by modifying the contents of the MOBY Central database, by means of a function call from the MOBY API (i.e., registerService). The service remains registered until the function deregisterService is called. This method has some shortcomings, mostly to do with security.

It is proposed (see email archives for details), that a better way of doing things would be to continue to allow registration by means of a function call. A key change is that the function would return an RDF document describing the service. The document would be placed at a pre-specified location on the web, and an RDF-reading agent would periodically check on the service's continued existence (the agent might visit hourly or weekly, depending on who you ask). Deregistration of the service would be a simple matter of removing the RDF document. On the agent's next visit, it would notice that the document had disappeared, and remove it from MOBY Central's registry.

Currently, it is possible to register a service under both schemes (to use the new scheme, simply provide a "signatureURL" parameter). However, there is currently no agent, therefore services registered under the new scheme will remain registered indefinitely. It is explicitly not allowed to deregister services which were registered using a signatureURL.