XML structure of an input message
What is passed into the service in the SOAP payload takes the following structure:
<?xml version="1.0" encoding="UTF-8"?> <moby:MOBY xmlns:moby="http://www.biomoby.org/moby"> <moby:mobyContent> <moby:mobyData queryID=''> <!-- articles (Simple/Collection/Secondary Parameter) required for first service invocation --> </moby:mobyData> [<moby:mobyData queryID=''> <!-- articles required for second service invocation --> </moby:mobyData>] ... ... </moby:mobyContent> </moby:MOBY>This message takes the form of a number of nested XML tags. The
mobyContent
envelope exists primarily as a container
for possible future use.
The mobyData
tags delimit the set of inputs to a single
invocation of the service, though there may be multiple
invocations in a single message, each contained within its own
enumerated mobyData
block. The contents of this block may be a Primary
article (Simple, or Collection),
or a Secondary article, which are Parameters used to modify the service behaviour.
Any request sent to a service with no mobyData
blocks
must be replied to with a MOBY payload containing no mobyData
blocks).
This is considered a basic "ping" functionality all MOBY-S Services must implement.
The queryID has no intrinsic meaning
Enumeration ofmobyData
elements is achieved by the
queryID
attribute of the mobyData
element,
whose value has no intrinsic meaning. The client
program should choose it be any legal XML attribute value, such that
it is unique to each mobyData
in the message. Service
providers should not attempt to interpret the value of
queryID
; it is simply an identifier. The service
provider must assign the same queryID
to the
associated mobyData
element in their response message
(described below). This allows the client program to match each query
with its corresponding response.
The articleName
attribute of the Simple
and/or Collection
elements is optional (it may or may not
be there, and if there, it may or may not have a non-null value), and
is used to invoke services that have named arguments; a single
queryInput
may contain multiple Simple
and/or Collection
articles that need to be
differentiated by name.
How to invoke a service with a Simple Article
For example, the retrieveSequence service registered above, that accepts a singleSimple
article as its input, would accept either of
the following SOAP message payloads for its service invocation:
<?xml version="1.0" encoding="UTF-8"?> <moby:MOBY xmlns:moby="http://www.biomoby.org/moby"> <moby:mobyContent> <moby:mobyData queryID='a1'> <Simple articleName='input1'> <Object namespace="NCBI_gi" id="163483"/> </Simple> </moby:mobyData> </moby:mobyContent> </moby:MOBY>For multiple invocations, the form is similar, except that the
mobyData
entity contains more than one
Simple
.
<?xml version="1.0" encoding="UTF-8"?> <moby:MOBY xmlns:moby="http://www.biomoby.org/moby"> <moby:mobyContent> <moby:mobyData queryID='a1'> <Simple articleName='input1'> <Object namespace="NCBI_gi" id="163483"/> </Simple> </moby:mobyData> <moby:mobyData queryID='a2'> <Simple articleName='input1'> <Object namespace="NCBI_gi" id="124454"/> </Simple> </moby:mobyData> </moby:mobyContent> </moby:MOBY>
How to invoke a service with a Collection Article
You invoke a service that requires aCollection
article
in a similar way to invoking one that requires just a
Simple
article:
<?xml version="1.0" encoding="UTF-8"?> <moby:MOBY xmlns:moby="http://www.biomoby.org/moby"> <moby:mobyContent> <moby:mobyData queryID='b1'> <Collection articleName="mySequenceCollection"> <Simple> <Object namespace="NCBI_gi" id="163483"/> </Simple> <Simple> <Object namespace="NCBI_gi" id="244355"/> </Simple> <Simple> <Object namespace="NCBI_gi" id="533253"/> </Simple> <Simple> <Object namespace="NCBI_gi" id="745290"/> </Simple> </Collection> </moby:mobyData> <moby:mobyData queryID='b2'> <Collection articleName="mySequenceCollection"> <Simple> <Object namespace="NCBI_gi" id="868483"/> </Simple> <Simple> <Object namespace="NCBI_gi" id="2492355"/> </Simple> </Collection> </moby:mobyData> </moby:mobyContent> </moby:MOBY>
How to invoke a service with Parameters
A message to a service that requires Secondary Articles is invoked as like this:<?xml version="1.0" encoding="UTF-8"?> <moby:MOBY xmlns:moby="http://www.biomoby.org/moby"> <moby:mobyContent> <moby:mobyData queryID='a1'> <Simple articleName='input1'> <Object namespace="NCBI_gi" id="163483"/> </Simple> <Parameter articleName='cutoff'> <Value>34</Value> </Parameter> </moby:mobyData> </moby:mobyContent> </moby:MOBY>Note that, even if present, the CRIB and PIB blocks of input MOBY objects should be ignored by the service. They may safely be stripped out of the input client-side prior to service invocation.