GrabDuck

Scripting and Web API

:

Latest news

Added support for digital booklets

Latest change

MinimServer update 101 has been released

Scripting and Web API [NEW]

Please do not redistribute this information or post a link to this page on any public website.

There is currently no official support for scripting and the web API. The following information is experimental and subject to change.

If you have any questions about these features, please send a private message to user simoncn via the MinimServer forum at forum.minimserver.com.

Table of contents

Command scripting [NEW]
Batch mode and interactive mode [NEW]
Some examples [NEW]
Command output [NEW]
Web API [NEW]

Command scripting [NEW]

MinimServer includes a scripting client application for controlling and configuring MinimServer. You can use this application to run a single MinimServer console command or a scripted list of MinimServer console commands (a command script). The available commands are listed in the Controlling MinimServer using console commands section.

The scripting client application must be run in a command prompt window (Windows) or a terminal window (Mac OS X or Linux). The command to run the scripting client application is named mscript and its location depends on which platform you are using, as follows:

  • On Windows, the mscript command is located in the bin folder underneath the folder where you installed MinimServer (normally C:\Program Files\MinimServer\bin\mscript.cmd).
  • On Mac OS X, the mscript command is located in the Contents folder within the MinimServer application (normally /Applications/MinimServer.app/Contents/mscript).
  • On Linux, the mscript command is located in the bin directory underneath the directory where you installed MinimServer.

The syntax of the mscript command is as follows:
mscript [ options ] [ script-file ]

where options is any combination of the following:

-i   use interactive mode
-a address   the host and port address of the server
-t timeout   the number of seconds (default 5) to wait for server response
-d   enable debug output
--help   show syntax summary

if you specify the script-file argument, mscript reads the command script from a file, which must be plain text. if you don't specify the script-file argument, mscript reads the command script from the standard input stream, which can either be connected to an interactive console or redirected to read input from a pipe or a file.

If the mscript command is invoked with no options or arguments and the standard input stream isn't redirected, mscript displays a syntax summary. If you want to read commands from an interactive console with defaults for all options, you can use the command mscript -i to do this.

The host and port address of the server can be an IP address (for example, 192.168.1.20) or an IP address and port number (for example, 192.168.1.20:9792). If this address isn't specified, the mscript command runs the command script on a MinimServer instance running on the local machine. You might need to specify a port number (for example, 192.168.1.20:9792) if MinimServer has been configured to use a custom HTTP port number instead of the default port 9790.

The command script can contain any number of commands. Lines starting with '#' are ignored. If the script contains multiple commands, the commands must be separated by newline characters.

Batch mode and interactive mode [NEW]

The mscript command can run in either batch mode or interactive mode. The -i option is used to specify interactive mode. If this option isn't specified, the default setting is interactive mode if mscript is reading commands from an interactive console and batch mode in all other cases.

In batch mode, mscript sends a list of commands (a command script) to MinimServer and MinimServer runs these commands in sequential order until the end of the script is reached or a command returns an error. The output from the last command to be run (either sucessfully or with an error) is written by mscript to the standard output stream in the format described in the Command output section below. Batch mode is useful for running a fixed sequence of commands.

In interactive mode, mscript reads a single command and sends it to MinimServer for processing. When the command completes (either successfully or with an error), mscript writes the command output to the standard output stream in the format described in the Command output section below. After writing the command output, mscript continues processing by reading the next command and sending it to MinimServer for processing. Command processing ends when mscript reads a null command (empty string) or reached the end of the command script. Interactive mode is useful if mscript is reading commands from an interactive console or if mscript is being controlled programmatically by another application.

Some examples [NEW]

Here are some examples of how the mscript command can be used:

mscript myscript.txt 
reads a command script from a file named myscript.txt and runs the commands in batch mode on a MinimServer instance running on the local machine
mscript -i 
reads commands from an interactive console and runs the commands in interactive mode on a MinimServer instance running on the local machine
myprog | mscript 
runs the program myprog to output a command script that is piped to the mscript command and run in batch mode by a MinimServer instance on the local machine
myprog | mscript -i 
runs the program myprog to output a command script that is piped to the mscript command and run in interactive mode by a MinimServer instance on the local machine
mscript <infile >outfile  
reads the command script from the file infile, runs the command script in batch mode and writes the command output to the file outfile
mscript -a 192.168.1.20 myscript.txt 
reads a command script from a file named myscript.txt and runs the command script in batch mode on a MinimServer instance running on the machine with IP address 192.168.1.20
mscript -a 192.168.1.20:9792 myscript 
reads a command script from a file named myscript and runs the command script in batch mode on a MinimServer instance running on the machine with IP address 192.168.1.20 and HTTP port number 9792

Command output [NEW]

mscript writes the output from running the command script (in batch mode) or each individual command (in interactive mode) to the standard output stream. This output is in three parts:

  • The last command that was run, preceded by the prefix +*
  • The output from the command
  • A status line of the form +:status=n, where n is the status returned be the command (see below)

For example, the command 'about' might produce the following output:
+*about
MinimServer
0.8.4, Copyright (c) 2012-2016 Simon Nash. All rights reserved.
+:status=0

and the command 'install foo' might produce the following output:
+*install
foo
Download
resource not found: foo.jmpkg
+:status=1

The following commands are treated specially:

restart restarts the server and waits for the server to restart. If any commands follow this command in the script, they are run after the server has restarted.
relaunch  relaunches the server and waits for the server to relaunch. If any commands follow this command in the script, they are run after the server has relaunched.
exit terminates the server. If any commands follow this command in the script, an error is returned for the first following command.

If all commands in the script were run by the server without error, the exit status from running the script is 0. If a command in the script was run by the server and returned a error, the exit status from running the script is 1. If the command script couldn't be sent to the server, an error message is written to the standard error stream and the exit status from running the script is 2 if the server address wasn't found or 3 for any other error.

Web API [NEW]

The MinimServer web API provices a mechanism for applications to send commands programmatically to MinimServer. An example of an application that does this is the mscript scripting client application (see the Command scripting section).

The web API uses the standard HTTP protocol. An application that needs to control MinimServer using the web API must send an HTTP POST request to the URL
http:// address : port /
where address is the IP address of the machine runing MinimServer and port is the HTTP server port that MinimServer is using on this machine (see the HTTP server port section). The content type for the request must be text/plain and the content data must be a command script containing console commands listed in the Controlling MinimServer using console commands section.

The command script can contain any number of commands. Any lines starting with '#' are ignored. If the script contains multiple commands, the commands must be separated by newline characters. MinimServer runs each command in the script in sequence until all commands have completed successfully or any of the commands returns an error. If a command returns an error, no more commands are run.

The HTTP POST response content data has a content type of text/plain and contains the last command that was run and the output from this command, preceded by the prefix +*. For example, the command 'about' might return the following:
+*about
MinimServer
0.8.4, Copyright (c) 2012-2016 Simon Nash. All rights reserved.

and the command 'install foo' might return the following:
+*install
foo
Download
resource not found: foo.jmpkg

The following commands are treated specially:

restart restarts the server and waits for the server to restart. If any commands follow this command in the list, they are run after the server has restarted.
relaunch  relaunches the server. If any commands follow this command in the list, the HTTP status code 503 (server unavailable) is returned for the first following command.
exit terminates the server. If any commands follow this command in the list, the HTTP status code 503 (server unavailable) is returned for the first following command.

If all commands complete successfully, the HTTP POST response status code is 200. If an error occurs while running a command, the HTTP POST response status code is 400 or greater.