Marvin Live developer guide - sending data

From version 15.4.2 it is possible to share links to rooms and from version 15.4.6 it is possible to send chemical files from external applications. This document describes the technical details of such an integration.

Linking to domains and rooms

The browser address bar URL is automatically updated as the user interacts with the application to create bookmarkable and shareable links. Matching this scheme allows external tools to generate working links to Marvin Live.

The links have the following syntax:

http://hostname:port/rooms/ domainName / roomName

Segment

Description

domainName

Name of the domain where the user is currently logged in, as defined in config.json’s authentication section (install guide).

Example: /rooms/internal

roomName

Name of the meeting room the user has joined, with encoding that changes spaces to underscores and adds URL encoding.

Example: Mike's ideas becomes /rooms/internal/Mike's_ideas

A sample JavaScript function that creates this string is:

function encodeRoomName(roomName) {
 return encodeURIComponent(roomName.replace(/ /g, "_"));
}

Security

When a user clicks on a link, they are directed to the specified domain and room, by first logging in (and logging out from a different domain if needed), and then by selecting a display name before joining the room. This means even when knowing the link, only authorized users can access the contents of a room.

Sending chemical files from external applications

External applications may send content to Marvin Live, by sending a POST request to the upload API endpoint. This endpoint accepts:

  • multipart requests with a single chemical structure file - which may contain more than 1 actual chemical structure

  • JSON requests with the source of a chemical structure file - which may contain more than 1 actual chemical structure

The response in both cases includes URL with a unique ID - located in the redirect for multipart request, and in a JSON object for JSON request, opening this URL in the client browser will make the contents of the file available in the first meeting room joined. If not authenticated, the client browser will also be taken through the login process.

Supported formats

Chemical file formats recognized by this module include MRV by default, but when converterService option is configured (install guide), other formats are automatically supported: SDF, SMILES, CDX, etc…

Multipart request

A browser file upload form produces a valid multipart request, when the form ’s action attribute and the file input ’s name attribute are specified as below:

<form action="http://marvinlive-example.com/upload/api"
   enctype="multipart/form-data" method="post">
 <input type="file" name="structures" />
 <button>Upload</button>
</form>

When submitted, this sends the following HTTP request:

POST /upload/api HTTP/1.1
Host: marvinlive-example.com
Content-Type: multipart/form-data; boundary="the_boundary"
Content-Length: number_of_bytes_in_entire_request_body
--the_boundary
Content-Disposition: form-data; name="structures"; filename="records.mrv"
Content-Type: application/octet-stream
 
Chemical file data
--the_boundary--

Response

If the request succeeds, the server returns HTTP 302 Moved temporarily status code, along with a redirect URL containing a unique ID that references the parsed contents of the file. Integrating applications can open this URL in the user’s browser.

HTTP/1.1 302
Location: /?cache=1164293e37ca9d47cbdfded5

JSON request

A valid request has the Content-Type of application/json and the body contains a JSON structure, with the file contents under the structures key.

POST /upload/api HTTP/1.1
Host: marvinlive-example.com
Content-Type: application/json
Content-Length: number_of_bytes_in_entire_request_body
{ "structures": "chemical file data" }

JSON response

If the request succeeds, the server returns a simple JSON object containing a unique URL that references the parsed contents of the file. Integrating applications should open this URL in the user’s browser.

HTTP/1.1 200
{
"url": "/?cache=1164293e37ca9d47cbdfded5"
}

Recommended implementations

For web applications, the simplest solution would prepare a form and programmatically submit it, to instruct the browser to perform the upload request. With a redirect in the response, the browser would then automatically open Marvin Live and take the user through the login/join process.

  1. generate valid chemical file

  2. prepare form with correct parameters

  3. submit form

Since most web applications would have a host different from Marvin Live’s, the Same-Origin Policy may prevent specific solutions from functioning. In this case, the recommended solution is to enable allowCrossOriginUploads option (install guide) and use the JSON request option.

For desktop applications, the simplest solution would send a JSON request and wait for the response. Using the URL in the response, the application would then send a browser open command to the operating system.

  1. generate valid chemical file

  2. send POST request with the file contents

  3. find URL in the response

  4. open the specified link in a browser