Application Program Interfaces

MxLIVE relies on MxDC as a source of meta-data from data collection sessions on the beamline, and acts as a resource from which MxDC can fetch sample information. While this close-coupling is tailored to MxDC, all connections are handled through the use of APIs, so other data collection applications could also be modified to complement MxLIVE.

All API urls begin with /api/v2/.

MxDC Integration

Security

For new project accounts, the UpdateUserKey API can be used to post a new key to the MxLIVE account. If a key already exists in MxLIVE, this will fail.

class mxlive.remote.views.UpdateUserKey(**kwargs)

API for adding a public key to an MxLIVE Project. This method will only be allowed if the signature can be verified, and the User object does not already have a public key registered.

Key

r’^(?P<signature>(?P<username>):.+)/project/$’

The remaining APIs for integration with MxDC must be verified using the account’s key through a VerificationMixin.

class mxlive.remote.views.VerificationMixin

Mixin to verify identity of user. Requires URL parameters username and signature where the signature is a string that has been time-stamped and signed using a private key, and can be unsigned using the public key stored with the user’s MxLIVE User object.

If the signature cannot be successfully unsigned, or the User does not exist, the dispatch method will return a HttpResponseNotAllowed.

Sessions

To start an MxLIVE session (when MxDC is opened), use the LaunchSession API. This will join an existing session if there is one that has been active in the past seven days, or create a new session. To close a session, use CloseSession. In cases where MxDC closes unexpectedly and the CloseSession call is not made, the next time any user attempts to launch a new session on the beamline, existing active sessions are closed.

class mxlive.remote.views.LaunchSession(**kwargs)

Method to start an MxLIVE Session from the beamline. If a Session with the same name already exists, a new Stretch will be added to the Session.

Key

r’^(?P<signature>(?P<username>):.+)/launch/(?P<beamline>)/(?P<session>)/$’

class mxlive.remote.views.CloseSession(**kwargs)

Method to close an MxLIVE Session from the beamline.

Key

r’^(?P<signature>(?P<username>):.+)/close/(?P<beamline>)/(?P<session>)/$’

Samples

MxDC can fetch samples belonging to a project account through ProjectSamples. This returns a list of any on-site samples for the account that are NOT currently loaded in the automounter of a different beamline. For samples loaded in the automounter of the active beamline, the location of the samples is also included.

class mxlive.remote.views.ProjectSamples(**kwargs)

Return

Dictionary for each On-Site sample owned by the User and NOT loaded on another beamline.

Key

r’^(?P<signature>(?P<username>):.+)/samples/(?P<beamline>)/$’

Datasets and Reports

Datasets and Analysis Reports can be uploaded to MxLIVE through AddData and AddReport. A minimum set of information is required for each API, and the ID of the new object in MxLIVE is returned.

While the directory for the dataset or report is required for these APIs, that information is not stored in MxLIVE. Rather, it is sent to the MxLIVE Data Proxy. The Data Proxy returns a secure key which is stored in MxLIVE and used to fetch files and data through the Data Proxy, since MxLIVE has no direct access to dataset and report files on disk.

class mxlive.remote.views.AddData(**kwargs)

Method to add meta-data about Data collected on the Beamline.

Parameters

• username – User__username

• data_id – If updating an existing Data object

• directory – Path to files

• energy – float (in keV)

• type – str (one of the acronyms defined for a Data Type)

• exposure – float (in seconds)

• attenuation – float (in percent)

• beam_size – float (in microns)

• name – str

• filename – filename (if single frame) or formattable template (e.g. “test_{:0>4d}.img”)

• beamline – Beamline__acronym

• sample_id – If known

• frames – frames collected (e.g. “1-4,8,10-99”),

• start_time – Starting time for data acquisition. If omitted, will be now - frames * exposure time

• end_time – End time for data acquisition. If omitted and start_time, is provided, will be start_time + frames * exposure_time, otherwise it will be now

Return

{‘id’: < Created Data.pk >}

Key

r’^(?P<signature>(?P<username>):.+)/data/(?P<beamline>)/$’

class mxlive.remote.views.AddReport(**kwargs)

Method to add meta-data and JSON details about an AnalysisReport.

Parameters

• username – User__username

• data_id – Data objects referenced

• score – float

• type – str

• details – JSON dict

• name – str

• beamline – Beamline__acronym

Return

{‘id’: < Created AnalysisReport.pk >}

Key

r’^(?P<signature>(?P<username>):.+)/report/(?P<beamline>)/$’

For details regarding the formatting of new MxLIVE reports, submitted as details to AddReport, see Formatting Reports.

Remote Connection Access Lists

This is an API to provide a list of users who should have access to a specific remote connection.

GET provides the list of users defined for the remote connection matching the IP address of the request.

POST is used to create and maintain a history of remote connections. Data provided should be in the form of a list of dictionaries including, at a minimum, the following information:

• project: Should match a username for a project account in MxLIVE

• status: One of the following strings: “Connected”, “Disconnected”, “Failed”, “Finished”

• date: Formatted to match “%Y-%m-%d %H:%M:%S”

• name: A unique identifier for the connection

class mxlive.remote.views.AccessList(**kwargs)

Returns list of usernames that should be able to access the remote server referenced by the IP number inferred from the request.

Key

r’^accesslist/$’