The XML protocol used by MMDS to communicate with a webservice is described in detail.

Overview

Example

Details

List

Specification

Type: info

Type: line

Type: text

Type: number

Type: flag

Type: option

Type: molecule

Type: datasheet

Invocation

Results

Overview


Since version 1.1, both the BlackBerry and iOS versions of the Mobile Molecular DataSheet app have included a webservice client. This allows the app to be connected to a particular web URL which describes some number of available services.

The means of communication between the mobile client and webservice is quite straightforward. An MMDS-compatible webservice can be constructed with a middleware development environment, such as PHP or Java Servlets. All client-server communication is done through the HTTP protocol. The client POSTs an XML document, and the server returns an XML document.

Example


The entire lifecycle of communication between the client and a webservice, or a group of webservices, goes through the following steps:

  1. The client connects to a URL and sends a GET request, e.g.:
  2. http://server.org/webapp/list.php?list
    
    

  3. The server responds by returning an XML document which enumerates one or more services, e.g.
  4. <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <MMDS_WebApps>
        <App name="SearchCatalog">
            <Description>Search for molecules within the online catalog.</Description>
            <URL>http://server.org/webapp/SearchCatalog.php</URL>
        </App>
        <App name="SubmitStructure">
            <Description>Submit a new structure for inclusion into the catalog.</Description>
            <URL>http://server.org/webapp/SubmitStructure.php</URL>
        </App>
    </MMDS_WebApps>
    
    

  5. The client makes a note of which services are available. If one of them is to be invoked, the specification of the webservice is requested using a GET request, e.g.
  6. http://server.org/webapp/SearchCatalog.php?spec
    
    

  7. The server responds with an XML document that describes the service and the parameters that it needs in order to run, e.g.
  8. <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <MMDS_WebSpec>
        <Name>SearchCatalog</Name>
        <Description>Search for molecules within the online catalog.</Description>
        <Fields>
            <structure type="molecule">
                <Title>Structure:</Title>
                <DefaultVal/>
                <Format>MDLMOL</Format>
            </structure>
    
            <resultlimit type="number">
                <Title>Maximum Results:</Title>
                <DefaultVal>20</DefaultVal>
                <MinVal>1</MinVal>
                <MaxVal>1000</MaxVal>
                <NumDecimals>0</NumDecimals>
            </resultlimit>
        </Fields>
    </MMDS_WebSpec>
    
    

  9. The client examines the specification and provides the user with a way to select values for each of the parameters. Then, the client formulates its own query document, and sends it to the service via a POST request, e.g.
  10. http://server.org/webapp/SearchCatalog.php?invoke
    
    

    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <MMDS_WebQuery>
        <Parameters>
            <structure><![CDATA[
    SketchEl molfile
    
      3  2  0  0  0  0  0  0  0  0999 V2000
       -5.3500    3.3000    0.0000 C   0  0  0  0  0  0  0  0  0  0	0  0
       -4.0510    4.0500    0.0000 C   0  0  0  0  0  0  0  0  0  0	0  0
       -2.7519    3.3000    0.0000 O   0  0  0  0  0  0  0  0  0  0	0  0
      1  2  1  0  0  0  0
      2  3  1  0  0  0  0
    M  END]]></structure>
            <resultlimit>100</resultlimit>
        </Parameters>
    </MMDS_WebQuery>
    
    

  11. The server carries out the search, and formulates a response document, e.g.
  12. <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <MMDS_WebResults>
        <Errors/>
        <Results>
            <MDLSDF><![CDATA[
    SketchEl molfile
    $title=Catalog Query for CCO
      3  2  0  0  0  0  0  0  0  0999 V2000
       -3.8010    2.2510    0.0000 C   0  0  0  0  0  0  0  0  0  0	0  0
       -4.5510    3.5500    0.0000 C   0  0  0  0  0  0  0  0  0  0	0  0
       -3.8010    4.8490    0.0000 O   0  0  0  0  0  0  0  0  0  0	0  0
      1  2  1  0  0  0  0
      2  3  1  0  0  0  0
    M  END
    > <Name>
    ethanol
    
    > <Description>
    good health
    
    $$$$
    
    SketchEl molfile
    
      2  1  0  0  0  0  0  0  0  0999 V2000
       -1.3500    3.6500    0.0000 O   0  0  0  0  0  0  0  0  0  0	0  0
       -1.3500    2.1500    0.0000 C   0  0  0  0  0  0  0  0  0  0	0  0
      1  2  1  0  0  0  0
    M  END
    > <Name>
    methanol
    
    > <Description>
    not so good health
    
    $$$$
    ]]></MDLSDF>
        </Results>
    </MMDS_WebResults>
    
    

Details


The following sections describe the 4 different types of XML documents that are used to pass information back and forth between the client and the server.

List


In order for the MMDS client to be aware of a webservice, it must be given a URL, typically entered by the user. During the discovery process, the client sends a GET request to the server. The URL is always passed with the GET parameter "?list" appended to it, e.g. http://server.org/webapp/list.php?list.

The server must return a document with MIME type text/xml. The root node must be <MMDS_WebApps>. For each individual application being described in the listing, there must be one descendent element with the tag <App>, as shown in the following scheme:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<MMDS_WebApps>
    <App name="{name1}">
        <Description>{description1}</Description>
        <URL>{url1}</URL>
    </App>
    <App name="{name2}">
        <Description>{description2}</Description>
        <URL>{url2}</URL>
    </App>
    ...
    <App name="{nameN}">
        <Description>{descriptionN}</Description>
        <URL>{urlN}</URL>
    </App>
</MMDS_WebApps>

Each <App> must have a name attribute, which should be a short token composed of alphanumeric characters, and no spaces. The name will be displayed prominently on the client device, and so should be as informative as possible, and preferably shorter than 20 characters, due to screen size constraints. Use of mixed case is recommended, e.g. "DoSomething".

A <Description> must also be provided for each individual application. It should be a single sentence, and terminate with a full stop. The description should be both informative and concise.

The <URL> is the basic entrypoint for the application service. The URL must be fully specified, and uniquely identify the application. If multiple applications are being listed, they cannot share the same URL.

Specification


The application listing provides a brief description of each available application, and the URL necessary to connect to it. Before an application can be invoked, it must be queried to find out what parameters it requires. The specification is obtained by sending a GET request, in which "?spec" is appended to the URL, e.g. if the base URL is http://server.org/webapp/DoSomething, then the specification must be returned in response to a request for http://server.org/webapp/DoSomething?spec.

The specification follows this template:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<MMDS_WebSpec>
    <Name>{appname}</Name>
    <Description>{description}</Description>
    <Fields>
        <{name1} type="{type1}">
            ...options...
        <{/name1}>
        <{name2} type="{type2}">
            ...options...
        <{/name2}>
        ...
        <{nameN} type="{typeN}">
            ...options...
        <{/nameN}>
    </Fields>
</MMDS_WebSpec>

Note that the <Name> and <Description> tags are redundant with the application listing. The name is reiterated as a simple consistency check. The description is repeated, because it is possible that the application specification may change after the initial application discovery.

The bulk of the specification is dedicated to a list of <Fields>, which provide all of the input information that a webservice requires in order to operate. Each of the fields is ultimately reduced to a single data value, but is presented to the user as a distinct user interface widget within a dialog box. The webservice itself does not need to be overly concerned with layout or presentation, but it does need to provide a sufficiently informative description of each field so that the user knows what is required.

Every field has a name attribute. These names must be alphanumeric and contain no spaces. Names must also be unique within the field list, since they will be used for identifiers in subsequent communications. The field names are never displayed to the user.

Each field has an assigned type attribute. The type determines which tags are required to describe the field. The tags that are listed as options should always be defined, though it is always valid to leave the text content empty, in which case some default interpretation will be used. The following sections describe the list of elements which are mandatory or optional for each type of field.

Type: info


The info field is the only type that does not map to any required data from the user. It simply displays text, which is typically used as a prelude description of a group of fields. As a general rule, it should be used whenever the Title elements do not provide sufficient space to clarify the purpose of a field.

  • Info: Provide the text to be displayed to the user. It should typically be in the form of a short sentence, terminated by a full stop.

Type: line


The line field requests a text string, which is restricted to a single line, and may have white space trimmed from it. Generally it is used for short tokens, such as names or search strings.

  • Title: Optionally provide a title for the field. The title should be as brief as possible, preferably one or two words.
  • MinSz: If specified as a non-negative integer, the line is required to have at least this many characters.
  • MaxSz: If specified as an integer greater than one, the line is required to have no more than this many characters.
  • Password: If set to true, then the line will be displayed in password mode, i.e. some character such as an asterisk will be displayed instead of the actual content. Note that this does not make any guarantees about the security of the data being transmitted to the webservice. It only prevents the text from being displayed on the screen.
  • DefaultVal: The initial value for the field.

Type: text


The text field requests a text string which may span multiple lines. When formulated into a request, it will be wrapped within a CDataSection, so whitespace will be preserved.

  • Title: Optionally provide a title for the field. The title should be as brief as possible, preferably one or two words.
  • DefaultVal: The initial value for the field. If this is provided as a CDataSection, whitespace preservation will be ensured.

Type: number


The number field requests a numeric value, which may either be an integer or floating point value, depending on the requested precision.

  • Title: Optionally provide a title for the field. The title should be as brief as possible, preferably one or two words.
  • MinVal: If provided as a valid number, the input value must be equal to or greater than this.
  • MaxVal: If provided as a valid number, the input value must be equal to or less than than this.
  • NumDecimals: If specified as a valid non-negative integer, this option constrains the number of decimal places allowed for the input. A value of 0 ensures that the input number will be integral.
  • DefaultVal: If specified, will be used as the default value. Otherwise, a value of 0 is used.

Type: flag


The flag field is a boolean value which has two possible states: true or false. These are encoded in XML text as literal strings, i.e. "true" and "false". The flag field is represented to the user as a checkbox.

  • Title: Optionally provide a title for the field. The title should be as brief as possible, preferably one or two words.
  • DefaultVal: If this value is "true", the initial state will default to true. Otherwise it will default to false. The string translation is case sensitive.

Type: option


The option field provides a list of options which the user may choose from. The value of this field will always be a string literal that corresponds to one of the provided options.

  • Title: Optionally provide a title for the field. The title should be as brief as possible, preferably one or two words.
  • Options: This element must be one child element for each of the options. The name of the child elements is arbitrary. For example, the specification for a list of three available options could be given as:
  • <Options>
        <O>One</O>
        <O>Two</O>
        <O>Three</O>
    </Options>
    
    

  • DefaultVal: If the value given matches one of the options, then this is used as the default. If it does not match, or is blank, the first option is used as the default.

Type: molecule


The molecule field prompts the user to provide a single molecular structure.

  • Title: Optionally provide a title for the field. The title should be as brief as possible, preferably one or two words.
  • Format: Must be one of the two values SketchEl or MDLMOL. This determines the format in which the molecular structure is transmitted by the client. If the server is capable of interpreting SketchEl molecules, then this format is recommended, since there is no possibility for information loss. For interfacing with most software, using the MDL MOL format is more convenient.
  • DefaultVal: A blank or invalid value is equivalent to an empty molecule. Otherwise, it should define the default molecular structure, using the appropriate format. It is recommended that the value be enclosed within a CDataSection to ensure that whitespace trimming is not an issue.

Type: datasheet


The datasheet field prompts the user to provide a datasheet.

  • Title: Optionally provide a title for the field. The title should be as brief as possible, preferably one or two words.
  • Format: Must be one of the two values DataSheet or MDLSDF. This determines the format in which the datasheet is transmitted by the client. The DataSheet format is an XML format used by MMDS. If the server is capable of interpreting this format, then it should be used, since the transmission involves no information loss. For interfacing with most software, the MDL SDfile format is more convenient, but it is necessary to be wary of the limitations of this format, e.g. only one molecule field per entry.
  • DefaultVal: A blank or invalid value is equivalent to an empty datasheet. Otherwise, it should define the default datasheet, using the appropriate format. XML datasheets should be embedded directly into the XML document, i.e. there should be one child element, called <DataSheet>, which wraps all of the content. MDL SD files should be enclosed in a CDataSection to ensure that whitespace trimming is not an issue.

Invocation


Once the specification for a web application is known, and values for each of the fields have been obtained, the webservice can be invoked. This is done by accessing the base URL, with "?invoke" appended to the end, e.g. if the base URL is http://server.org/webapp/DoSomething, then the execution of the webservice is carried out by accessing http://server.org/webapp/DoSomething?invoke.

The invocation request is made as a POST rather than a GET. The client must transmit an XML document which contains values for each of the required fields. The general template for a query request document is:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<MMDS_WebQuery>
    <Parameters>
        <{field1}>{value1}</{field1}>
        <{field2}>{value2}</{field2}>
        ...
        <{fieldN}>{valueN}</{fieldN}>
    </Parameters>
</MMDS_WebQuery>

Each of the fields referred to within the specification is referenced by name, as an individual element. The element contains the value associated with that field. The field values should be packaged up as described for the DefaultVal elements for the type. Most field types can be transmitted as plain text, but whitespace-sensitive data such as multiline strings and molecular structures should be enclosed within a CDataSection. XML datasheets should be directly embedded as XML child nodes.

Results


The webservice will respond to an invocation request with an XML document which takes the following general form:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<MMDS_WebResults>
    <Errors>
        <E>{error1}</E>
        <E>{error2}</E>
        ...
        <E>{errorN}</E>
    </Errors>
    <Results>
        ...
    </Results>
</MMDS_WebResults>

If the webservice successfully with no problems, then the <Errors/> element will be empty, and the <Results> element will be non-empty. If there are both errors and results, then the errors can be considered to be warnings.

The <Results> element will contain no child elements if the request failed entirely. Otherwise, the return data will be made available in one of two forms, which is indicated by the name of the child element. If the element is <MDLSDF>, then the content is a CDataSection which contains the resulting datasheet in the form of an MDL SD file. If the element is <DataSheet>, then the result data is an embedded XML datasheet.

See Also


Format: DataSheet Aspects, Format: SketchEl Molecule, Format: XML DataSheet, Interprocess communication amongst iOS apps, Mobile Molecular DataSheet (iOS), MolSync Remote Procedure Calls, Products, Property Calculations via Open Notebook Science, Searching ChEBI (iPhone), Searching PubChem (BlackBerry), WebService Code Example