Web Services¶

Extended Functionalities¶

Extended functionalities are only available when the web services are set up. These functionalities are as follows:

Clean 2D/3D
MolConvert
Stereoinfo
Hydrogenize
Automapper
Aromatize/Dearomatize (Default Protocol)
Aromatize/Dearomatize (JChem Micro Services Protocol)

The reactionconvert web service may be necessary because of backward compatibility. Recent Marvin JS can detect reaction component natively unlike older versions where the above-mentioned service is needed to do that. To activate the legacy behavior, see the Reaction Handling example.

Referring Web Services¶

By default, functionalities that require live connection to existing web services are disabled. To activate them, you have to specify the addresses of these web services for the editor.

Use the setServices method of the editor to apply the web service settings. See the API documentation for more details. If you want to activate all web services, see the How to Embed.

The default address of these services is defined in the webservices.js. It may point to a copy of JChem Web Services, Marvin JS Web Services, or JChem Micro Services. Optionally, the name of the protocol of each web service may also be specified (for details, see below).

If you have your own implementation for these services or your copy of any of the above mentioned web services is located on a different URL, you can overwrite default settings.

Specifying Protocol Name of Web Services¶

If not specified, all web service requests are sent according to the default protocol. However, some web services might use different protocols, which have to be specified in the webservices.js file or by invoking the setService() API method. In the passed JavaScript object, the property names correspond to the supported web services. The property values can either be a single string, representing the URL, or an other JavaScript object, containing the URL and the protocol name of the web service. If the protocol is not specified, its value is set to default.

In particular, the Aromatize/dearomatize web service has two implementations. The JChem Web Services and Marvin JS Web Services use the default protocols, but when the JChem Micro Services are used, the value of the protocol property must be set to JChemMicroservices.

{
    "clean2dws" : <url of Clean2D webservice>
    "clean3dws" : <url of Clean3D webservice>
    "molconvertws" : <url of MolConvert webservice>
    "stereoinfows" : <url of CIP Stereo Info webservice>
    "reactionconvertws" : <url of Reaction converter webservice>
    "hydrogenizews" : <url of hydrogenize webservice>
    "automapperws" : <url of auto mapper webservice>
    "aromatizews" : {
        "url" : <url of aromatize webservice>
        "protocol" : <protocol of aromatize webservice>
    }
}

Specification of Web Services¶

Those web services that are referred by Marvin JS have to complete the following specifications.

This specification is based on The Marvin JS Micro Services REST API.

Clean 2D/3D¶

Request¶

Type: application/json
Method: POST
Posted JSON object:

{ 
    "structure": <molecule source>, 
    "parameters": { 
        "dim": 2, 
        "opts": <optional clean options> 
    }
}

Parameters¶

Option	Type	Description
dim	integer	clean dimensions; 2 or 3
opts	string	further clean options (optional)

Response¶

Response-type: plain/text
Response text: results in MRV format

MolConvert¶

Without the MolConvert web service, only MDL molfile and MRV formats are supported for import and export actions.
When the MolConvert web service is available, it is possible to use any text-based chemical format that is supported by Marvin, for example, SMILES, InChi, naming, and so on.

Request¶

Type: application/json
Method: POST
Posted JSON object:

{ 
    "structure": <molecule source>, 
    "inputFormat": <input format>,
    "parameters": <output format>
}

Response¶

Response-type: application/json
Response text:

{
    "structure": <output structure>,
    "format": <output format>,
    "contentUrl": <download link>
}

Stereoinfo¶

Request¶

Type: application/json
Method: POST
Posted JSON object:

{ 
    "structure": <molecule source>
}

Response¶

Response-type: application/json
Response text:

{
    "tetraHedral" : [ 
        { 
            "atomIndex" : < 0 based index of atom>,
            "chirality" : < chirality flag ("R", "S", "R/S" )> 
        }, 
        ...
    ],
    "doubleBond" : [
        {
            "atomIndex1" : <0 based index of first atom of the bond>,"atomIndex2" : <0 based index of second atom of the bond>,
            "cistrans" : <cistrans info ("E", "Z", "E/Z")>
        },
        ...
    ]
}

reactionExport¶

Request¶

Type: application/json
Method: POST
Posted JSON object:

{ 
    "structure": <molecule source>, 
    "inputFormat": <input format>,
    "parameters": <output format>
}

Response¶

Response-type: application/json
Response text:

{
    "structure": <output structure>,
    "format": <output format>,
    "contentUrl": <download link>
}

Hydrogenize¶

Request¶

Type: application/json
Method: POST
Posted JSON object:

{ 
    "structure": <molecule source>, 
    "inputFormat": <input format>,
    "parameters": {
        "method": "HYDROGENIZE"
    }
}

Parameters¶

Option	Type	Description
method	string	command to perform: HYDROGENIZE or DEHYDROGENIZE
atoms	array of integers	a subset of atom indices to include or null for all

Response¶

Response-type: plain/text
Response text: results in MRV format

AutoMapper¶

Request¶

Type: application/json
Method: POST
Posted JSON object:

{ 
    "structure": <molecule source>, 
    "inputFormat": <input format>,
    "parameters": {
        "autoMappingStyle": "COMPLETE"
    }
}

Response¶

Response-type: plain/text
Response text: results in MRV format

Aromatize/Dearomatize (Default Protocol)¶

Request¶

Type: application/json
Method: POST
Posted JSON object:

{ 
    "structure": <molecule source>, 
    "inputFormat": <input format>,
    "parameters": <output format>,
    "filterChain": [
        {
            "filter": "standardizer",
            "parameters": {
                "standardizerDefinition": <"aromatize" or "dearomatize">
            }
        }
    ]
}

Response¶

Response-type: application/json
Response text:

{
    "structure": <output structure>,
    "format": <output format>,
    "contentUrl": <download link>
}

Aromatize/Dearomatize (JChem Micro Services Protocol)¶

Request¶

Type: application/json
Method: POST
Posted JSON object:

{ 
    "structures": [
        <molecule source>
    ],
    "inputFormat": <input format>,
    "parameters": <output format>,
    "method": <"aromatize" or "dearomatize">
}

Response¶

Response-type: application/json
Response text:

{
    [
        <output structure>
    ]
}