REST API

• 1. Overview
• 2. Database
• 3. API
  • 3.1 Introduction
  • 3.2 HTTP requests
  • 3.3 Commands
    • 3.3.1 ping
    • 3.3.2 auth
    • 3.3.3 show
    • 3.3.4 cmd
    • 3.3.5 img
    • 3.3.6 json

1. Overview

As mentioned in chapter "Command File" in section "Input" the mar345dtb may be driven by external commands. Starting with program version 16.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 mar345dtb 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 "mardtb" is available for free in the Google Play Store & Apple Store.

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 mardtb). 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 'mar' and 'admin' 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 'admin' with password 'mardtb' using command:

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

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

      mardb -d $MARTABLEDIR/mar.db -u admin mardtb

should return:

      INFO: Password for user 'admin' OK

Otherwise, it will either return:

      ERROR: User 'admin' does not exist
      or
      ERROR: Password for user 'admin' 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

3. API

3.1 Introduction

The API is a full featured interface, that can be used to do simple operations like opening and closing the mardtb 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 admin:mardtb 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 mardtb 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

3.2 HTTP requests

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

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

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.

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!

Examples:

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

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: mardtb @ IP-address (e.g. mardtb @ 192.168.0.88)

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 admin:mardtb http://localhost:8888/auth
Returns: Token: abcdefgh12345678

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/type

	TASK 34 IDLE OP 0 MOVING PHI DIO 6d7fc7e7 XRAY 28229 25892 SHUTTER CLOSED
	PHI           90.000  OP 0   4000
	CHI            0.000  OP 0   2107
	THETA          0.000  OP 0   2107
	...
		

3.3.4 cmd/args

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.

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

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 "Edit" 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.

Example: curl -H "Token: abcdefgh12345678" -H "Content-Type: application/json" -d '{"set":1, "nfrm":10, "time":5.0, "dphi":0.1, "dir":"/home/mar345/data", "root":"xtal"}' http://localhost:8888/json
Returns: {"message":"Command accepted","request":{"set":1,"nfrm":10,"time":5.0,"dphi":0.10000000000000001,"dir":"/home/mar345/data","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!