Marvin JS - Webservices

Extended functionalities

Extended functionalities means those features that are only available when web services are setup.

Clean 2D button is visible on the toolbar if Clean2D web service is available.
Importing molecule in any Marvin supported text based chemical format (SMILES, InChi, naming, ...) via the import dialog, if MolConvert web service is available. Without the desired service, only MDL molfile and MRV format are available.
Exporting molecule into any Marvin supported text based chemical format (SMILES, InChi, naming, ...) via the save dialog, if MolConvert web service is available. Without the desired service, only MDL molfile and MRV format are available.
Calculate Stereo button is visible on the toolbar if stereoinfo web service is available.
(De)hydrogenize button is available if hydrogenize web service is available.
Auto Map button is presented if automapper web service presents
(De)aromatize button is enabled if aromatize web service is available.
The reactionconvert web service may be necessary because of backward compatibility. Recent Marvin JS can detect reaction component natively unlike ancient version where above service is needed to do that. To activate the legacy behaviour, see the Reaction Handling example

Refer web services

By default, those functionalities in the editor that require live connection to existing web services are disabled. To activate them, you have to set up address of these web services for the editor.

Use the setServices method of the editor to apply its webservice settings. See the Sketch apidoc for more details. If you want to activate all web services, please, see the How To Embed section in the documentation that describes how you can insert an editor into a web page where all available web services are preset.

The default address of these services is defined in the webservices.js. It may point to a copy of JChem Webservices, Marvin JS Web Services or JChem Microservices. 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 (see below). The JChem Webservices and Marvin JS Web Services use the default protocol, but when JChem Microservices are used, the value of the protocol property has to 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 Webservices

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. Unlike this document is just a brief overview of this API, the Marvin JS Micro Service API doc give more details.

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 dimension: 2 or 3
  
  opts string further clean options (optional)
Response:
- Response-type: plain/text
- Response text: result in MRV format

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

MolConvert

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>
}

Stereo info

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" }
}
```
  Option Type Description
  
  method string command to perform: HYDROGENIZE or DEHYDROGENIZE
  
  atoms array of integer subset of atom indeces to include or null for all
Response:
- Response-type: plain/text
- Response text: result in MRV format

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

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: result 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 (JChemMicroservices 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>
	]
}
```

Back to index