User's Guide

marXperts GmbH
Werkstr.3
D-22844 Norderstedt / Germany
Tel. +49 (40) 529 884 0
www.marxperts.com

REST API

7.1. Overview
7.2. Database
7.3. API

7.1. Overview

As mentioned in chapter "Command File" in section "Input" the mar345 may be driven by external commands. Starting with program version 7.0, instead of receiving commands via a command file or via a TCP/IP-socket connection, it is also possible to run a REST server within the program that listens for HTTP requests. This feature is enabled with keyword "COMMAND REST <port> TOKEN <length>" in the mar345 configuration file when the given port number is a positive integer, e.g. 8888. The length of the token string defaults to 16 characters. HTTP requests can be sent via a web browser, via command line tools like curl or by implementing them in an app for mobile devices. There actually is an app for Android and iOS that makes use of this feature. The app "mar345" is available for free in the Google Play Store & Apple Store.

7.2. Database

For using the REST API, it is required to authenticate yourself before actually sending commands. The authentication requires a user name and password. Both will reside in a database, that can be created with program mardb (not to be confused with mar345). The default name and location for the data base file is $MARTABLEDIR/mar.db, but environment variable MARDB can be used to override that pathname. The username is a key in mar.db and the password is the encrypted value for this key. You may use any user and password but it is suggested to create users 'mar345' in order to use the program with the official app. In order to create an empty data base, do the following:

mardb -d $MARTABLEDIR/mar.db -c

You may now add users to that database, e.g. user 'mar345' with password 'mar345' using command:

mardb -d $MARTABLEDIR/mar.db -c -u mar345 -p mar345

In order to verify that the creation has been successful, the command

mardb -d $MARTABLEDIR/mar.db -u mar345 mar345

should return:

INFO: Password for user 'mar345' OK

Otherwise, it will either return:

ERROR: User 'mar345' does not exist
or
ERROR: Password for user 'mar345' does not match

Typical other command line arguments for program 'mardb' are:

-h : Usage help
-l : List keys and values in database
-r KEY : Remove key KEY in database

7.3. API

7.3.1 Introduction

The API is a full featured interface, that can be used to do simple operations like opening and closing the mar345 shutter and moving motors but also to start a beam optimization or beam search and even trigger and stop a data collection. For safety reasons only authenticated users may trigger actions on the hardware or obtain hardware information. A typical implementation of the program should therefore start with an authentication using a valid username and password (stored as encrypted strings in the database, see chapter 2). A successful authentication will return a webtoken, that will expire after some time. The webtoken is a string of given length, that from now on must be passed in the HTTP request header together with the actual command. The webtoken will be used instead of username and password to decide whether a user is allowed to issue a command or not. An authentication request using curl typically looks like this:

curl -u mar345:mar345 http://localhost:8888/auth

and typically returns something like:

Token: 8vwLGfss1EhgzeXD

In subsequent requests, the given token must be used to be able to e.g. open or close the mar345 shutter using a command like:

curl -H "Token: 8vwLGfss1EhgzeXD" http://localhost:8888/cmd/shutter/open

With a valid token, a command then typically returns:

OK: Command accepted

With a wrong or expired token, the return string would become:

ERROR: Token invalid: 8vwLGfss1EhgzeXD
or without token
ERROR: Token missing for /cmd/shutter/open

7.3.2 HTTP requests

Almost all HTTP requests are using the GET method (default) except for the "json" request, where data are passed to the server as a payload using the POST method. The general form of a HTTP request is:

[METHOD] [TOKEN] [TYPE] [DATA] URL/CMD

with the following [optional] parameters and their corresponding syntax:

Item	Example	Description
METHOD	-X GET \| POST"	POST is only required for "json" command.
TOKEN	-H "Token: string"	Optional webtoken returned by the authentication command URL/auth Must be provided in the header of the HTTP request for action commands.
TYPE	-H "Content-type: application/json"	Mandatory when used together with optional DATA, otherwise obsolete. Must be provided in the header of the HTTP request for certain action commands.
DATA	-d "{'Key' : 'value' }"	Parameters for programming a data set must be given in the data payload of the HTTP request. Details are described below.
URL	http://HOST:PORT	Base address of the HTTP request.
CMD	cmd/shutter/open	Actual hardware command.

The syntax for the CMD part is identical to the command interface, except for the following:

Small letters are MANDATORY! Other than on the command line interface where either small letters or capital letters may be used, the syntax on the REST API is case sensitive and only small letters are allowed.
Spaces between keywords have to be replaced by the backslash character "/". The CMD part of the URL must not contain empty spaces.
COMM must be replaced by string "cmd". Most action commands given on the REST API must start with string "cmd". A few other base commands may use other keywords (see below).

Thus, a command like "COMMAND MOVE PHI 90.0" given on the command line interface is converted to "cmd/move/phi/90.0". This conversion applies to all commands described on the command line interface and will therefore not be repeated here.

7.3.3 Commands

There are only very few base commands. A base command is the first instruction after the URL part of the HTTP request. If the syntax is invalid, the server returns the following string:
ERROR: command not implemented!

CMD	Parameters	Returns	Description
ping	none	mar345 @ IP-address	If program mar345 is not listening on the given URL, a standard error message like "Failed to connect to HOST port 8888: Connection refused" will be returned. The ping command is the only command that does not require a webtoken authentication.
auth	-u user:password	Token: string	The user name and password given with option -u is checked against entries in the database ($MARDB, see above). If a match is found, a webtoken is returned. The default token length is 16 characters. The webtoken is valid for a limited period of time. When expired, the authentication needs to be repeated in order to receive a new token.
show	TOKEN		Shows status information of the mar345. Details see below.
cmd/args	TOKEN	Depends on args	Trigger hardware action. Details see below.
img/args	TOKEN	Depends on args	Show information about image name, numbers, etc. If 'args' is 'jpg' or 'webp' or 'new', the command returns an actual graphics image as full binary file. Details see below.
json	TOKEN TYPE DATA	Depends on args	Start a data collection. Data collection parameters must be provided in the keyworded DATA section and the transfer method must be POST and not GET. Details see below.

Examples:

curl -H "Token: abcdefghi12345678" http://localhost:8888/img/new
curl -X POST -H "Content-Type: application/json" -H "Token: abcdefghi12345678" -d '{"nfrm":10, "ffrm":1, "time":5.0, "dphi":1.0, "dir":/home/mar345/data", "root":"xtal"}' http://localhost:8888/json

7.3.3.1 ping

The ping command is the only command that can be used without a webtoken. It can be used to see if the server is alive and listening.

Example: curl http://localhost:8888/ping
Returns: mar345 @ IP-address (e.g. mar345 @ 192.168.0.88)

7.3.3.2 auth

The user name and password given with option -u is checked against entries in the database ($MARDB, see above). If a match is found, a webtoken is returned. The default token length is 16 characters. The webtoken is valid for a limited period of time. When expired, the authentication needs to be repeated in order to receive a new token. The returned webtoken is required as authentication string for all other commands except 'ping'.

Example: curl -u mar345:mar345 http://localhost:8888/auth
Returns: Token: abcdefgh12345678

7.3.3.3 show

The "show" command is one of the base commands. It requires an additional argument. Depending on the choice, the string returned differs. The command is used to show status information about the hardware. It is mandatory to provide the webtoken obtained from authentication with the show command, i.e. all commands must be issued in the form similar to:

Example: curl -H "Token: abcdefgh12345678" http://localhost:8888/show
Returns: TASK 0 IDLE DONE 0 DIO 780800 XRAY 15.0 DISTANCE 100.000 IDLE PHI 0.000 IDLE SHUTTER CLOSED
The value after TASK is the current internal task number (e.g. 31 for MOVE DISTANCE). The value following DONE is a completeness indicator in percent while a task is active or 0 if no task is active. The value following DIO is a bitmask in hex notation for digital IO pins. The value following XRAY is the ionization chamber reading. For motors DISTANCE and PHI there is the current motor position and either the string IDLE or MOVING. The shutter status can be either OPEN or CLOSED.

7.3.3.4 cmd/args

The "cmd" command is one of the base commands. It requires an additional argument. Depending on the choice, the string returned differs. The command is used to trigger some hardware action. It is mandatory to provide the webtoken obtained from authentication with the "cmd" command, i.e. all commands must be issued in the form similar to:

Example: curl -H "Token: abcdefgh12345678" http://localhost:8888/cmd/shutter/open
Returns: OK: Command accepted

or in case of of an unknown argument:

Example: curl -H "Token: abcdefgh12345678" http://localhost:8888/cmd/unknown
Returns: ERROR: Invalid URL /cmd/unknown

CMD	Description
cmd/shutter/open	Opens mar345 shutter
cmd/shutter/close	Closes mar345 shutter
cmd/move/<motor>/<target>	Absolute movement of <motor> to target value Example: cmd/move/phi/120.0
cmd/init[/min]	Initialize DISTANCE at far end switch. Use additional argument 'min' to initialize at near end switch Example: cmd/init
cmd/abort	Abort all current motor movements, exposures and data collections. Example: cmd/abort
cmd/stop	Gently stop all current motor movements, exposures and data collections. Example: cmd/abort

The list of available commands is even longer. Essentially, all commands defined in the command interface on the "COMM" keyword can be used. The REST API only requires the keyword "COMM" to be replaced by "cmd", empty spaces between keywords by a single backslash "/" and all characters to be lowercase.

7.3.3.5 img/args

The "img" command is one of the base commands. It requires an additional argument. Depending on the choice, the string returned differs. The "img" command is used to show current image names and numbers for ongoing data collections. It can also be used to transfer graphical images produced out of the underlying diffraction images. For this to work, it is necessary to select the option "Save thumbnail for each image" in the set used for data collection. When this option is selected, the program will run a script that converts the diffraction image into either a jpg, png or webp graphical image. As of 2019, the webp format might be preferred since webp images are smaller than jpgs of comparable quality. The command to run to do the conversion is given on keyword "THUMBNAIL" in the configuration file (see section Input for details). It is assumed that the graphical images live in subdirectory jpg, png or webp of the data directory where the diffraction images are stored.

It is mandatory to provide the webtoken obtained from authentication with the "img" command, i.e. all commands must be issued in the form similar to:

Example: curl -H "Token: abcdefgh12345678" http://localhost:8888/img/name
Returns: IMAGE: /home/mar/data/xtal/xtal_00001.cbf 1

or in case of of an unknown argument:

Example: curl -H "Token: abcdefgh12345678" http://localhost:8888/cmd/unknown
Returns: ERROR: Invalid URL /cmd/unknown

CMD	Description
cmd/shutter/open	Opens mar345 shutter
cmd/shutter/close	Closes mar345 shutter
cmd/move/<motor>/<target>	Absolute movement of <motor> to target value

7.3.3.6 json

The "json" command is one of the base commands. It is used to provide parameters for a data collection and to actually start and run a data collection. Please note, that the command will be only be executed if the program is idle and not busy with some other hardware task.

It is mandatory to use the following parameters with the json command:

POST instead of GET as type of http request
the webtoken obtained from authentication in the header section with keyword "Token"
the argument "application/json" in the header section with keyword "Content-Type"
a keyworded data section with data collection parameters

In the data section, essentially all data set parameters that are visible on the "Single Data Set" page of the GUI can be speficied. Motor positions may or may not be given. If they are missing, current positions are assumed. The table lists the keywords, their default values and a description.

Keyword	Type	Default	Description
dir	String	auto	Data directory for series of images. Keyword "auto" means: default location as configured by keyword DIRECTORY in the configuration file (see section Input for details).
root	String	xtal	Root name of images in series
mode	Integer	current	Scanmode: one of 2300, 2000, 1600, 1200, 3450, 3000, 2400, 1800 or 1 to 8
nfrm	Integer	1	Number of images to be collected
ffrm	Integer	1	Starting image number
time	Float	1.0	Exposure time per image in sec
dphi	Float	1.0	Phi-range per image
iphi	Float	0.0	Phi movement inbetween 2 consecutive movements
MOTOR	Float	current	Motor position at start of data collection. MOTOR must be replaced by a valid motor name, one of: phi or distance.

Example: curl -H "Token: abcdefgh12345678" -H "Content-Type: application/json" -d '{"nfrm":10, "ffrm":1, "time":5.0, "dphi":1.0, "dir":"/home/mar345/data", "root":"xtal"}' http://localhost:8888/json
Returns: {"message":"Command accepted","request":{"nfrm":10,"ffrm":1,"time":5.0,"dphi":1.0,"dir":"auto","root":"xtal"}}

In case, the program is still busy, the following string will be returned: {"message":"Command accepted","request":{"title":"ERROR","message":"Program busy with other task!"}}

In case of an invalid token, the following string will be returned: ERROR: Token invalid: abcdefgh12345678

In case of a missing data section, the following string will be returned: ERROR: command not implemented!

IMPRINT